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	No	string	Blockchain network name (e.g., Bitcoin, Ethereum). Use a name from Read Blockchains for better delivery rates.
travel_rule.blockchain_info.transaction_hash	No	string	The on-chain transaction hash. Optional so the Travel Rule message can be created before the on-chain transaction exists; attach it later with Update Transaction.
travel_rule.blockchain_info.origin	No	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

vasp_info is optional. Send the beneficiary VASP details you know.

Parameter	Required	Type	Description
travel_rule.vasp_info.beneficiary_vasp_name	No	string	Name of the receiving VASP.
travel_rule.vasp_info.beneficiary_vasp_email	No	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	No	string	ISO 3166-1 alpha-2 country code of residence (natural person) or registration (legal person), e.g. US, GB, DE.
travel_rule.originator.national_identificator_type	No	string	Type of national ID. See National Identificator Types.
travel_rule.originator.national_identificator	No	string	National identification number.
travel_rule.originator.customer_number	No	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 when originator.type is NATURAL.

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	No	string	ISO 3166-1 alpha-2 country code.
travel_rule.beneficiary.national_identificator_type	No	string	Type of national ID. See National Identificator Types.
travel_rule.beneficiary.national_identificator	No	string	National identification number.
travel_rule.beneficiary.customer_number	No	string	Internal customer reference number used by your VASP.

National Identificator Types

Code	Description	IVMS101 equivalent
PAS	Passport number	CCPT
IDC	Identity card number	IDCD
ALN	Alien registration number	ARNU
DRV	Driver's license number	DRLC
RAI	Registration authority identifier	RAID
FIN	Financial identification number / tax ID in certain jurisdictions	FIIN
TXN	Tax identification number	TXID
SSN	Social security number	SOCS
LEI	Legal entity identifier	LEIX
OTH	Other	MISC

note

Send the code in the left column, in upper case. Any other value (including lower case, or TAX / PASSPORT) is rejected with request.invalid. The IVMS101 equivalent is shown for reference only — see Protocols & Standards.

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 an existing Travel Rule transaction: record your compliance decision on an INCOMING transaction, or add data to a transaction, such as the transaction_hash once the on-chain transfer exists.

caution

Which statuses you can set depends on the transaction's direction (see Updatable Statuses). The counterparty's response to an OUTGOING transaction arrives asynchronously — see Status Lifecycle.

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	No	string	New status. See Updatable Statuses. PENDING and FAILED are system-managed and cannot be set.
status_reasoning	Conditional	string	Required when status is DECLINED or CANCELLED. Provide clear, specific reasoning.
asset	No	string	Cryptocurrency asset code.
amount	No	number	Amount transferred.
blockchain_info	No	object	blockchain, transaction_hash, origin, destination_type — same fields as Create.
vasp_info	No	object	Same fields as Create.
originator	No	object	Same fields as Create.
beneficiary	No	object	Same fields as Create.

Updatable Statuses

For INCOMING transactions:

Status	Description	Reasoning Required
DELIVERED	Travel Rule message received.	No
CONFIRMED	You reviewed and accepted the transaction.	No
DECLINED	You reviewed and rejected the transaction.	Yes

For OUTGOING transactions:

Status	Description	Reasoning Required
DELIVERED	Travel Rule message delivered.	No
CANCELLED	You cancel the transaction.	Yes

Setting a status that the direction does not allow (for example DECLINED on an OUTGOING transaction) is rejected with an error such as Updating status to DECLINED is not allowed for outgoing transactions.

Sample: Attach Transaction Hash

attach-transaction-hash

{
  "transaction_id": "695798278f0a2bda14017663",
  "blockchain_info": {
    "transaction_hash": "b3c4d5e6f7a8b9c0d1e2f3456789abcdef0123456789abcdef0123456789abcd"
  }
}

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 or cancelling a transaction, you must provide status_reasoning with a clear explanation. Omitting it returns 422.

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"
}