Transaction lifecycle

Each movement is one transaction. A collection is one transaction, and a payout is one transaction. Every transaction moves through stages.

The timeline field shows this progress. It is a set of steps in order, and the text is for your users. You can show the steps directly as a status stepper.

Status

The transaction's overall status is a summary you can show as a pill:

Status	Meaning
`pending`	Created, not yet moving.
`processing`	In flight — one or more steps are underway.
`success`	Completed — funds delivered / credited.
`failed`	Could not be completed.
`cancelled`	Cancelled before completion.

We calculate the status from the steps. If one step fails, the transaction fails. If all the steps succeed, the transaction succeeds. If neither is true, the transaction is in progress. You do not calculate the status.

The timeline

Each transaction response includes a timeline array. Each entry is one stage:

{
  "status": "processing",
  "timeline": [
    { "stage": "requested",  "message": "We received your request",          "status": "completed",   "occurred_at": "2026-06-25T10:16:57.000Z" },
    { "stage": "debited",    "message": "Funds debited from your balance",    "status": "completed",   "occurred_at": "2026-06-25T10:16:57.000Z" },
    { "stage": "processing", "message": "Converting and routing your funds",  "status": "in_progress", "occurred_at": "2026-06-25T10:17:00.000Z" },
    { "stage": "sent",       "message": "Sent to the destination",            "status": "pending",     "occurred_at": null },
    { "stage": "delivered",  "message": "Funds delivered",                    "status": "pending",     "occurred_at": null }
  ]
}

Entry fields

Field	Meaning
`stage`	Canonical stage identifier (stable; safe to switch on).
`message`	Friendly copy — safe to show end-users verbatim.
`status`	`completed`, `in_progress`, or `pending`.
`occurred_at`	When the step last advanced, or `null` if not yet reached.

Stages

`stage`	Typical `message`	When
`requested`	We received your request	Transaction created.
`received`	Payment received	Customer's pay-in arrived (collections).
`debited`	Funds debited from your balance	Your balance debited (payouts).
`processing`	Converting and routing your funds	Mid-flight.
`sent`	Sent to the destination	Handed off to the recipient's bank/wallet.
`delivered`	Funds delivered	Recipient credited.
`failed`	This transfer could not be completed	Terminal failure.
`reversed`	This transfer was reversed	Reversed after the fact.

A transaction does not always use every stage, and a collection is different from a payout. But the stages are always in order. Show the stages that the response gives you.

Rendering tips

Build your stepper directly from timeline. Put a tick on each completed step, a spinner on the in_progress step, and no mark on a pending step.
Show the summary status as a pill above the stepper.
The message text is for your users. Show it, and do not change it.

Transactions created before the timeline shipped return an empty timeline array. Always handle the empty case.

Money Model

Corridors