Skip to main content
GET
Get step-by-step payment timeline
The timeline is for reconciliation and support — a step-by-step record of what happened to a payment. To decide what to do next with a payment, read status from payment status instead. See Reconciliation.

Path Parameters

paymentId
string
required

The ID of the payment to query

Response

Timeline retrieved successfully

Step-by-step view of a payment's settlement lifecycle. Includes a route summary, a list of steps with timings, and if the payment failed, a structured error describing where and why.

payment_id
string
required
Example:

"0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f"

status
enum<string>
required

Where your payment is in its lifecycle. One payment reads the same however you ask about it.

  • pending: accepted and in progress. Nothing has reached the recipient yet.
  • finalizing: the transaction paying your recipient is on chain and is accruing the confirmations its chain requires. NOT FINAL, see below.
  • completed: delivered, with the required confirmations behind it.
  • failed: did not complete. Any funds held in escrow are returned, and error describes what went wrong.

completed and failed are final and will not change afterwards. pending and finalizing will.

Do not treat finalizing as delivered. It says the payment has been made on chain but is not yet irreversible, much as a card authorization is not yet a settlement. It normally becomes completed, and it can still become failed if the transaction never reaches the confirmation depth its chain requires. Acting on finalizing — releasing goods, crediting an account — means accepting that risk deliberately, at whatever threshold suits you rather than the one we wait for.

finalizing is about paying the recipient. While your own funds are still being committed on the source chain the payment is pending, because nothing has reached the recipient yet.

Available options:
pending,
finalizing,
completed,
failed
Example:

"pending"

created_at
string<date-time>
required
updated_at
string<date-time>
required
steps
object[]
required
transactions
object

The transactions a payment has produced, one entry per stage, added as each becomes known. A stage absent here has produced no transaction yet.

These are the two movements that decide whether your payment happened: your funds being committed, and your recipient being paid. Present on every outcome, so a payment that did not complete can still be traced on chain. fulfillment_confirmation is not a substitute: it is written only once a payment completes, and describes the finished delivery rather than progress towards it.

Where a stage is attempted more than once, the entry describes the attempt that counts — the one that succeeded, or the last one if none did.

total_duration_ms
integer<int64>

Total time from first step to last completed step (only set for terminal states)

summary
object

Top-level context about the payment (parties, assets, amounts)

error
object

Why a payment failed. Present only when status is failed, and identical however you ask about the payment.

code is the stable, machine-readable identity of the failure — branch on it rather than on message, which is written for a person and may be reworded. docs_url points at the page describing that code.