Travel Rule beneficiary information

Provide beneficiary information when Travel Rule collection is enabled for your account and a payment meets both conditions:

• The funding amount is $3,000 or more, including exactly $3,000.
• The sender and recipient are different users.

This applies to Standard and Instant payments. TBMC collects the information when you create the payment order. Originator information comes from your account's KYB record. You do not send originator fields.

Check the account policy

Call GET /api/v1/travel-rule/requirements with your API key. Use subaccountId to check a direct subaccount.

Omit beneficiary for payments below $3,000 or between the same user, even when the policy is required.

Collect the beneficiary

Add a top-level beneficiary object to POST /api/v1/payment. Use the same object in POST /api/v1/rulesets.

Country and subdivision use the same parameter names for both beneficiary types. Country accepts two- or three-letter ISO codes. For example, USA becomes US. Subdivision accepts CA or US-CA for California and stores US-CA. TBMC requires a subdivision when the country has listed regions. Omit it when the country has no listed regions.

Individual beneficiary

This example shows the beneficiary field to add alongside your payment or auto route parameters:

{
  "beneficiary": {
    "type": "individual",
    "givenName": "Jamie",
    "familyName": "Lee",
    "dateOfBirth": "1988-03-22",
    "location": { "country": "US", "subdivision": "US-CA" },
    "isSelfHosted": true
  }
}

Business beneficiary

{
  "beneficiary": {
    "type": "business",
    "legalName": "Example Company LLC",
    "location": { "country": "US", "subdivision": "US-NY" },
    "isSelfHosted": false,
    "legalEntityIdentifier": "<wallet provider LEI from the search endpoint>"
  }
}

The LEI identifies the wallet provider, not the beneficiary business. For a self-hosted destination, omit legalEntityIdentifier or send an empty string. TBMC stores the other fields and marks the payment ineligible for sharing.

Find a hosted wallet provider

Search GET /api/v1/travel-rule/vasps?q=provider-name&page=0&perPage=25. Authentication uses your API key. Results contain name, legalEntityIdentifier, country, and website. Pages start at zero; perPage accepts 1–100.

Search accepts partial names. Select the correct legal entity and copy its legalEntityIdentifier into the beneficiary. Only providers with a usable LEI appear. At creation, TBMC requires an exact LEI match to one supported provider.

If the provider is missing or the LEI matches multiple providers, creation returns 400. Confirm the legal entity or contact TBMC. Directory outages return 503; retry the same creation request with its idempotency key.

Auto routes

When the policy is required, include beneficiary information when creating an auto route, before its deposit amounts are known. TBMC saves it on the auto route and copies it to qualifying payment orders. Payments below $3,000 or between the same user remain exempt. GET /api/v1/rulesets/{id} returns the saved beneficiary.

Read the sharing status

GET /api/v1/payment-orders/{paymentOrderId} includes travelRule when beneficiary information was collected. The object contains the saved beneficiary, an eligible boolean, and the sharing status below. Hosted wallets are eligible for sharing; self-hosted wallets are ineligible.

Sharing runs asynchronously after funding when delivery is enabled. Collection and delivery can be enabled separately; pending does not promise immediate submission. These statuses describe information sharing and do not change payment settlement status.