Start exchange after settlement

Learn how to submit compliant after on-chain incoming transfer when receiving a blockchain transaction.

Use this flow when a transfer has already settled on the blockchain and arrived without Travel Rule data. You create the exchange after the fact to collect what is missing.

Most often this is a deposit your user received unannounced. The sender may simply not have run the exchange, or may sit in a sunrise jurisdiction — a country that has not brought the Travel Rule into force yet — where nothing obliged them to send anything with the transfer.

You still hold the obligation to obtain the data, so you request it directly.

Key flow parameters include the following:

  • You create the exchange.
  • info.direction is in.
  • info.paymentTxnId is required.

The same flow also covers the rare case where your user sent funds and you are supplying the data retrospectively — set info.direction to out. Nothing else changes. If you find yourself doing this routinely, move those withdrawals to the before-settlement flow instead.

📘

Tip

If the blockchain transaction has not been submitted yet, use the Start exchange before settlement flow.

If another VASP has already created a request for this transfer, answer theirs instead of creating a second record — use the Answer incoming request flow.

Before you start, complete the common setup.

How exchange after settlement works

The funds have already moved, and nothing gates a payment in this case. You are producing a record. One of the following happens:

  • The counterparty identifies their customer and you hold a complete Travel Rule dataset for the transfer.
  • The counterparty does not identify their customer, and you hold documented evidence that you requested customer identification.

Note that answer rates are lower than for before-settlement requests, because the counterparty has no transfer of their own waiting on the reply. That is a reason to run the before-settlement flow wherever you can, not a reason to skip this one.

Start data exchange after settlement

The following is a sequence of steps to be taken to start data exchange after settlement.

Step 1: Check for existing exchange

Creating a second exchange for a transfer that already has one is the most common error in this flow. It produces two records that both need answering, and the counterparty sees a duplicate.

Look the transfer up using this API method, working down this list and stopping at the first search that returns a single unambiguous match.

Request example:

// Checks whether a Travel Rule inbound transaction with a specific crypto hash and sender wallet already exists.

curl -X GET \
     'https://api.sumsub.com/resources/kyt/txns/query/-;data.type=travelRule;data.applicant.paymentMethod.accountId=0x611Fb08528080848Dd3439242fdfg993d18ADd95dsd;data.info.direction=in;data.info.paymentTxnId=000000000000000000013f2851d71e6ea8dfcc9151654ca4cbbbfd759122589f?order=-createdAt&limit=1' \
     -H 'accept: application/json' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>'
  1. Use the blockchain transaction hash.
  2. Use the counterparty wallet address and asset when the hash is not indexed yet. Enough for most deposits, but a counterparty who sends you many transfers from the same address will return several matches.
  3. Add the amount and a time window around the settlement. This narrows the previous search down to one transfer when the address alone is not selective enough.

Only create a new exchange when nothing comes back.

📘

Note

A counterparty who ran the before-settlement flow will already have created the exchange, and it will be sitting on your account waiting for your answer. Check before you create, or you will answer one record and start another.

Step 2: Submit transfer

Send the transfer:

The fields that define this flow:

FieldValue
typetravelRule
info.directionin
info.paymentTxnIdThe on-chain transaction hash. Required in this flow.

Omitting info.paymentTxnId turns this into a before-settlement exchange. The counterparty will then be asked to authorise a transfer that has already happened, and the flow will not behave as you expect.
applicantYour user — the sender.
counterparty.paymentMethod.accountIdThe address the funds came from.
counterparty.institutionInfo.internalIdThe sending VASP, if you already know which it is.
infoamount, currencyCode, currencyType: "crypto", chain parameters
📘

Note

Field requirements differ by protocol and by participant type. For more information, see the protocol requirements.

Step 3: Attribution and protocol selection

Sumsub identifies the sending VASP and delivers the request. Identifying the counterparty matters as much here as it does on withdrawals. You have the same two options as on a withdrawal, and the same trade-off between them.

  1. Let your user pick the VASP. This option is recommended. If you can determine the sending VASP from your own records — your deposit-address mapping, your transaction history, or simply by asking the user where the funds came from — pass it as counterparty.institutionInfo.internalId and attribution is skipped entirely.

    The same directory that backs a withdrawal VASP picker works for this flow.
  2. Send only the address. Sumsub attributes it against the wallet address databases, the Travel Rule protocols and blockchain analytics providers. This is the right fallback, but a significant share of addresses cannot be attributed at all.
📘

Tip

You can also let the Travel Rule SDK collect what is missing: create the transaction as above, then open the SDK on it and your user supplies the sending VASP and the counterparty details themselves.

One of the following scenarios then happen:

  1. Counterparty identified and reachable → awaitingCounterparty. The request is delivered and you wait.
  2. Counterparty identified, no shared protocol → counterpartyVaspNotReachable. Sumsub still emails the VASP about this transfer, and the attempt is recorded in the Dashboard under EventsEmails for you to export as evidence. For more information on email notifications, see this article.
  3. No VASP attributed → counterpartyVaspNotFound. The destination is treated as an unhosted wallet and your unhosted wallet configuration takes over — asking the user to prove ownership of the address before the withdrawal proceeds. For more information, refer to this article.

Your confirmation timeout determines how long you wait. When it elapses the exchange becomes expired and is re-scored against your rules.

Step 4: Review counterparty response

The review outcome your rules produce arrives as applicantKytTxnApproved, applicantKytOnHold or applicantKytTxnRejected. To see the whole list of webhooks with their descriptions, refer to this article.

For deposits that have already landed, you can configure the appropriate action for each Travel Rule outcome in your rule bundle.

applicantKytTxnAwaitingUser means the transaction is waiting on your own user, typically to complete wallet ownership verification. It does not mean you are waiting on the counterparty.

The status of the Travel Rule exchange tells you what happened with the counterparty and what evidence you are left holding.

StatusWhat it meansWhat you hold
finishedThe counterparty answered, the data reconciled, and the record is closed against the on-chain transfer.A complete Travel Rule record for the transfer.
counterpartyMismatchedDataTheir data did not reconcile with yours.A discrepancy to review manually.
counterpartyVaspGeneralDeclineThey declined to supply the data.A documented refusal.
expiredNo answer within your timeout.Documented evidence that you requested data.
counterpartyVaspNotFound / counterpartyVaspNotReachableNo counterparty to ask, or no way to reach them.An unattributed deposit, handled by your rules.
📘

Important

You do not finalise this flow yourself. In this flow, Sumsub finalises the exchange for you: as soon as the counterparty answers and the exchange completes, the transaction moves straight to finished.

Do not call the update method to try to force it. A successful exchange in this flow should arrive at finished on its own. For more information on statuses, lifecycle, and outcomes, see this article.

Protocol requirements

Which fields are mandatory depends on the protocol the counterparty VASP speaks. If they are missing, the exchange ends at notEnoughCounterpartyData before anything is sent.

ProtocolIndividualCompany
SumsubNothing extra for your own user. For the counterparty, the fields you require are the ones you configured in your Travel Rule matching settings.
CODEtype, wallet address, and a name — either fullName or firstNameEn + lastNameEn + nameType. dob is required for your own user only.type, wallet address, fullName, address.country, and the CEO firstNameEn + lastNameEn + nameType
GTRtype and a name, same rule as CODE. Wallet address is required for the counterparty only.type and fullName

Wallet address is required for the counterparty only.
📘

Important

On CODE and GTR, an exchange with info.direction: in also requires the blockchain transaction ID.


Did this page help you?