type. A status change is named after the new status value, so the types reuse the words /status already uses: the commit is route_intent.submitted, not “committed”.
The
data shapes are the two shapes /status returns: the pending payload before a commit, and the transaction payload after it. Payload has an example of each.
Trustware may add event types. Return
2xx for any type you don’t
recognize, and ignore it. Don’t treat an unknown type as an error, or your
endpoint will fail deliveries it should have accepted.Which types end a route intent
route_intent.success and route_intent.failed are final for the transfer.
route_intent.expired is final unless the transaction lands late. If the payer’s transaction is committed after expiry, you receive route_intent.submitted and the route intent carries on from there. Don’t release or reuse anything tied to the route intent on expired alone if a late payment would still matter to you.
Refunds arrive as failed
A refunded transfer is reported as failed, the same way /status reports it. There’s no separate refund type. data.refunded is true when the routing provider reported that it returned the input to the sender. A false doesn’t rule out a refund, because refund reporting is provider dependent. Don’t trigger any downstream payout until you receive route_intent.success.
One change, several events
One update can fire more than one type. For example, a status check that sees the transfer complete and the destination transaction at the same time firesroute_intent.success and route_intent.destination_tx_seen together. They get consecutive sequence numbers and carry the same data, so you can handle each independently.
When that happens, the events are numbered in this order:
- the status type, if
statuschanged route_intent.source_tx_replacedroute_intent.destination_tx_seen- one
route_intent.approve_confirmedper newly confirmed approve step, by step index
sequence rather than arrival order to tell which came first.
A typical sequence
Here is one possible sequence for a deposit that completes normally:
The types you receive depend on the route and on what the routing provider reports, so don’t hard-code this order.
route_intent.destination_tx_seen can arrive while the route intent is still bridging, and a route that needs a token approval starts with one or more route_intent.approve_confirmed events before route_intent.submitted.