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, but its chain has not yet judged it final. NOT FINAL, see below.
  • completed: delivered and final on the destination chain.
  • failed: did not complete. Any funds held in escrow are returned, and error describes what went wrong.
  • refunding: the settler will not deliver this payment and your funds are being returned from escrow. NOT FINAL: it becomes refund_available or refunded, and it can still become completed or failed.
  • refund_available: the settler did not deliver and the refund is authorized for you to submit. GET /v1/payments/{paymentId}/status returns refund_signature, which you submit to the source escrow to return your funds. The other responses report this status without the signature. NOT FINAL: the funds are still in escrow, so it becomes refunded once the refund lands, or completed if the settler delivers late and is paid first. Do not pay again while it is refund_available.
  • refunded: your funds were returned from the source escrow. transactions.refund is the refund transaction, when it is known.

completed, failed and refunded are final and will not change afterwards. pending, finalizing, refunding and refund_available 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, after seconds on some chains and minutes on others. If a chain reorganization drops the transaction before it is final, your funds are refunded instead. 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,
refunding,
refund_available,
refunded
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 movements that decide whether your payment happened: your funds being committed, your recipient being paid, and your funds being returned when the payment is refunded. Present on every outcome, so a payment that did not complete can still be traced on chain.

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, or why its settler gave up. As error it is present only when status is failed, as refund_reason only on the refund statuses, and it is 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.

refund_reason
object

Why the settler did not deliver, as it reported when it gave up. Present only when status is refunding, refund_available or refunded, and absent when the refund started without a reason from the settler. status decides what to do next: its retry_classification and request_id_reusable describe the settler's error, not this payment, and never mean paying again while it is refunding or refund_available.