Transactions

The Transactions API allows you to create, read, update, and delete Travel Rule transactions for crypto asset transfers. These endpoints enable full lifecycle management of Travel Rule compliance data.

Create Transaction

Create a new Travel Rule transaction for crypto asset transfers. Provide comprehensive originator and beneficiary information along with blockchain details to ensure compliance with FATF, MiCA, and other regulations.

Create Transaction is dispatched through Shufti's main verification endpoint by including a travel_rule block in the request body. The type field selects the Travel Rule operation - transaction is the default and may be omitted.

Endpoint

POST {{BASE_URL}}/

note

This is the same / endpoint used by other Shufti verification services. Authenticate using Basic Auth with your client_id and secret_key (or an Access Token), exactly as described in Get Started - Authentication.

Request Body

The Travel Rule transaction payload is sent as a travel_rule block inside the standard Shufti verification envelope (reference, callback_url, etc.).

create-transaction-request
{
  "reference": "sp-tr-txn-001",
  "callback_url": "https://webhook.site/your-unique-id",
  "travel_rule": {
    "type": "transaction",
    "direction": "OUTGOING",
    "asset": "BTC",
    "amount": 0.875,
    "blockchain_info": {
      "blockchain": "bitcoin",
      "transaction_hash": "b3c4d5e6f7a8b9c0d1e2f3456789abcdef0123456789abcdef0123456789abcd",
      "origin": "1FfmbHfnpaZjKFvyi1okTjJJusN455paPH",
      "destination": "bc1q8g9w8rj9h0w0v3n9z6q6h4j5y7x9c2f8r4d3pq",
      "destination_type": "CUSTODIAL"
    },
    "vasp_info": {
      "beneficiary_vasp_name": "Global Digital Assets Exchange Ltd",
      "beneficiary_vasp_email": "[email protected]",
      "beneficiary_vasp_extra_info": "Regulated VASP registered in the US."
    },
    "originator": {
      "type": "NATURAL",
      "name": "Michael Thompson",
      "account_number": "GB-TRX-458721",
      "address": "221 Baker Street, London",
      "country": "GB",
      "national_identificator_type": "PAS",
      "national_identificator": "GBR458721963",
      "customer_number": "CUS-GB-102938",
      "date_of_birth": "20-06-1987",
      "place_of_birth": "Manchester"
    },
    "beneficiary": {
      "type": "NATURAL",
      "name": "Daniel Carter",
      "account_number": "US-TRX-785412",
      "country": "US",
      "national_identificator_type": "IDC",
      "national_identificator": "USA874512369",
      "customer_number": "CUS-US-564738"
    }
  }
}

Travel Rule Service Type

Parameter	Required	Type	Description
travel_rule.type	No	string	Travel Rule operation type. Accepts `transaction` (default) or `wallet_verification`. Omit to default to `transaction`.

General Parameters

Parameter	Required	Type	Description
travel_rule.direction	Yes	string	Transaction direction: `OUTGOING` or `INCOMING`.
travel_rule.asset	Yes	string	Cryptocurrency asset code (e.g., `BTC`, `ETH`, `USDT`).
travel_rule.amount	Yes	number	Amount of asset transferred in the specified cryptocurrency.

Blockchain Parameters

Parameter	Required	Type	Description
travel_rule.blockchain_info.blockchain	Yes	string	Blockchain network name (e.g., `Bitcoin`, `Ethereum`).
travel_rule.blockchain_info.transaction_hash	Yes	string	The on-chain transaction hash.
travel_rule.blockchain_info.origin	Yes	string	Originating wallet address.
travel_rule.blockchain_info.destination	Yes	string	Destination wallet address.
travel_rule.blockchain_info.destination_type	Yes	string	Destination wallet type: `CUSTODIAL` or `NON_CUSTODIAL`.

VASP Parameters

Parameter	Required	Type	Description
travel_rule.vasp_info.beneficiary_vasp_name	Yes	string	Name of the receiving VASP.
travel_rule.vasp_info.beneficiary_vasp_email	Yes	string	Email for the receiving VASP's compliance team.
travel_rule.vasp_info.beneficiary_vasp_extra_info	No	string	Additional VASP info (LEI, license number, etc.).

Originator Parameters

Parameter	Required	Type	Description
travel_rule.originator.type	Yes	string	Entity type: `NATURAL` (person) or `LEGAL` (company/organization).
travel_rule.originator.name	Yes	string	Full name of the originator.
travel_rule.originator.account_number	Yes	string	Wallet address or account identifier.
travel_rule.originator.address	Yes*	string	Physical address. Required for `NATURAL` type persons.
travel_rule.originator.country	Yes	string	ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`, `DE`).
travel_rule.originator.national_identificator_type	Yes	string	Type of national ID. See National Identificator Types.
travel_rule.originator.national_identificator	Yes	string	National identification number.
travel_rule.originator.customer_number	Yes	string	Internal customer reference number used by your VASP.
travel_rule.originator.date_of_birth	Yes*	string	Date of birth in `DD-MM-YYYY` format. Required for `NATURAL`.
travel_rule.originator.place_of_birth	Yes*	string	Place of birth (city, country). Required for `NATURAL`.

note

Fields marked Yes* are required only for NATURAL type persons.

Beneficiary Parameters

Parameter	Required	Type	Description
travel_rule.beneficiary.type	Yes	string	Entity type: `NATURAL` (person) or `LEGAL` (company/organization).
travel_rule.beneficiary.name	Yes	string	Full name of the beneficiary.
travel_rule.beneficiary.account_number	Yes	string	Wallet address or account identifier.
travel_rule.beneficiary.country	Yes	string	ISO 3166-1 alpha-2 country code.
travel_rule.beneficiary.national_identificator_type	Yes	string	Type of national ID. See National Identificator Types.
travel_rule.beneficiary.national_identificator	Yes	string	National identification number.
travel_rule.beneficiary.customer_number	Yes	string	Internal customer reference number used by your VASP.

National Identificator Types

Code	Description
`PASSPORT` (or `PAS`)	Passport number
`IDC`	Identity card number
`ALN`	Alien registration number
`DRV`	Driver's license number
`RAI`	Registration authority identifier
`FIN`	Foreign investment identity number
`TAX` (or `TXN`)	Tax identification number
`SSN`	Social security number
`LEI`	Legal entity identifier
`OTH`	Other identification type

Response

The transaction is created and screened asynchronously, so POST / returns the standard Shufti envelope with event: request.pending immediately. The screening outcome is delivered later to your callback_url as a signed verification.accepted / verification.declined callback — see Responses › Callbacks.

create-transaction-response
{
  "reference": "sp-tr-txn-001",
  "event": "request.pending",
  "email": null,
  "country": null
}

note

Creation is asynchronous — POST / returns request.pending immediately, and customer_unique_id is echoed when you supply it. The full transaction object (with _id, status, parties, etc.) is retrieved from the Read and Transaction Detail endpoints; its fields are described below.

Transaction Object (returned by Read / Transaction Detail)

Parameter	Description
_id	Unique identifier of the transaction.
reference	Your own `reference` from the create request, attached by Shufti for correlation.
direction	Transaction direction: `INCOMING` or `OUTGOING`.
asset	Cryptocurrency asset code (e.g., `BTC`, `ETH`).
amount	Transaction amount in the specified asset.
status	Current status: `PENDING`, `FAILED`, `CANCELLED`, `DELIVERED`, `CONFIRMED`, or `DECLINED`.
status_reasoning	Explanation for status change. Null unless `DECLINED`.
created_at	Timestamp in RFC 2822 format.
warnings	Array of warnings or validation messages.
travel_rule_message_source	Source reference for the Travel Rule message.
identified_tenant	Additional tenant/organization information.
blockchain_info	Blockchain-specific details (blockchain, hash, origin, destination, type).
vasp_info	Counterparty VASP details (name, email, extra info).
originator	Originator data (mirrors request parameters).
beneficiary	Beneficiary data (mirrors request parameters).

Read Transactions

Retrieve Travel Rule transactions with filtering, search, and pagination. Fetch all transactions, filter by status, search by criteria, and retrieve detailed information for compliance reporting.

Endpoint

GET {{BASE_URL}}/travel-rule/transaction/read

Query Parameters

All parameters are optional. Without parameters, the endpoint returns the first 25 transactions.

Parameter	Required	Type	Description
page	No	integer	Page number for pagination. Defaults to `1`.
per_page	No	integer	Results per page. Defaults to `25`, maximum `100`.
search	No	string	Search by transaction `_id`, customer name, or account number, or by your own `reference`.
start_date	No	string	Start date in `DD-MM-YYYY` format.
end_date	No	string	End date in `DD-MM-YYYY` format.
statuses[]	No	array	Filter by status: `PENDING`, `FAILED`, `CANCELLED`, `DELIVERED`, `CONFIRMED`, `DECLINED`. Repeat parameter for multiple values.
direction	No	string	Filter by direction: `INCOMING` or `OUTGOING`.

Response

Returns a transactions array and pagination metadata.

read-transactions-response
{
  "error": false,
  "status": "SUCCESS",
  "message": "Transaction fetched successfully",
  "data": {
    "transactions": [ ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total_count": 2,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
}

Pagination Fields

Parameter	Description
data.pagination.page	Current page number.
data.pagination.per_page	Results per page.
data.pagination.total_count	Total number of matching transactions.
data.pagination.total_pages	Total pages available.
data.pagination.has_next	Boolean: whether a next page exists.
data.pagination.has_prev	Boolean: whether a previous page exists.

Transaction Detail

Retrieve detailed information for a specific Travel Rule transaction by its unique identifier. Ownership of the transaction is verified before the data is returned.

Endpoint

GET {{BASE_URL}}/travel-rule/transaction/detail

Query Parameters

You must provide the transaction identifier using either transaction_id (preferred) or search as a fallback.

Parameter	Required	Type	Description
transaction_id	Yes*	string	The unique `_id` of the transaction to retrieve. Preferred parameter.
search	Yes*	string	Alternative parameter accepting the transaction `_id`. Used as a fallback when `transaction_id` is not provided.

note

At least one of transaction_id or search must be provided. If both are omitted (or empty), the request fails with 422 and an error message: transaction_id is required.

Sample Request

GET {{BASE_URL}}/travel-rule/transaction/detail?transaction_id=TRANSACTION_ID

The response structure is identical to Read Transactions, with the transactions array containing exactly one transaction.

Update Transaction

Update the status of an existing Travel Rule transaction. This endpoint can only update transactions with INCOMING direction.

caution

This endpoint can only update transactions with INCOMING direction. Attempting to update an OUTGOING transaction will result in an error.

Endpoint

POST {{BASE_URL}}/travel-rule/transaction/update

Request Parameters

Parameter	Required	Type	Description
transaction_id	Yes	string	Unique identifier of the transaction to update.
status	Yes	string	New status: `DELIVERED`, `CONFIRMED`, or `DECLINED`.
status_reasoning	Conditional	string	Required when status is `DECLINED`. Provide clear reasoning.

Updatable Statuses

Status	Description	Reasoning Required
`DELIVERED`	Transaction successfully delivered to counterparty VASP.	No
`CONFIRMED`	Transaction confirmed and accepted by counterparty.	No
`DECLINED`	Transaction declined/rejected by counterparty.	Yes

Sample: Confirm Transaction

confirm-transaction
{
  "transaction_id": "695798278f0a2bda14017663",
  "status": "CONFIRMED"
}

Sample: Decline Transaction

decline-transaction
{
  "transaction_id": "695cb01826ae544d2f497410",
  "status": "DECLINED",
  "status_reasoning": "Beneficiary failed AML screening - sanctioned entity"
}

caution

When declining a transaction, you must provide status_reasoning with a clear explanation. Omitting reasoning for DECLINED status will result in an error.

Response

Returns the complete updated transaction object (same shape as Read) with message: "Transaction status updated successfully".

update-transaction-response
{
  "error": false,
  "status": "SUCCESS",
  "message": "Transaction status updated successfully",
  "data": {
    "_id": "695798278f0a2bda14017663",
    "status": "CONFIRMED",
    "status_reasoning": null,
    "direction": "INCOMING"
  }
}

Delete Transaction

Permanently delete a Travel Rule transaction from the system.

danger

Deletion is permanent and irreversible. This may impact compliance audit trails. Use with caution.

Endpoint

POST {{BASE_URL}}/travel-rule/transaction/delete

Request Parameters

Parameter	Required	Type	Description
transaction_id	Yes	string	Unique identifier of the transaction to delete.

Sample Request

delete-transaction-request
{
  "transaction_id": "TRANSACTION_ID"
}

Response

delete-transaction-response
{
  "data": {},
  "error": false,
  "message": "Transaction deleted successfully",
  "status": "SUCCESS"
}

Create Transaction​

Endpoint​

Request Body​

Travel Rule Service Type​

General Parameters​

Blockchain Parameters​

VASP Parameters​

Originator Parameters​

Beneficiary Parameters​

National Identificator Types​

Response​

Transaction Object (returned by Read / Transaction Detail)​

Read Transactions​

Endpoint​

Query Parameters​

Response​

Pagination Fields​

Transaction Detail​

Endpoint​

Query Parameters​

Sample Request​

Update Transaction​

Endpoint​

Request Parameters​

Updatable Statuses​

Sample: Confirm Transaction​

Sample: Decline Transaction​

Response​

Delete Transaction​

Endpoint​

Request Parameters​

Sample Request​

Response​

Create Transaction

Endpoint

Request Body

Travel Rule Service Type

General Parameters

Blockchain Parameters

VASP Parameters

Originator Parameters

Beneficiary Parameters

National Identificator Types

Response

Transaction Object (returned by Read / Transaction Detail)

Read Transactions

Endpoint

Query Parameters

Response

Pagination Fields

Transaction Detail

Endpoint

Query Parameters

Sample Request

Update Transaction

Endpoint

Request Parameters

Updatable Statuses

Sample: Confirm Transaction

Sample: Decline Transaction

Response

Delete Transaction

Endpoint

Request Parameters

Sample Request

Response