Skip to main content
GET
Get payment status

Path Parameters

paymentId
string
required

The ID of the payment to query

Response

Payment status retrieved successfully

payment_id
string

The payment ID you're checking status for.

Example:

"0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f"

status
enum<string>

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"

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.

updated_at
string<date-time>

When the status was last updated

quote_id
string

The winning quote's ID. Present once a quote has been awarded for this payment; absent while the payment is still collecting or awarding. Cross-references the quote_id returned by GET /v1/payments/quote-requests/{quoteRequestId}.

Example:

"0x9a3b...e8d4"

fulfillment_quote
object

The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an opaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has been awarded — including after the payment completes and fulfillment_confirmation is populated, since that is precisely when a consumer verifies.

This is the PREIMAGE of the quote_hash committed on-chain in the escrow deposit and reserve witnesses. On-chain we commit only the hash, so a quote-selector consumer recomputes quote_hash over these bytes and compares it against the on-chain commitment to confirm the payment settled against the quote it selected ("trust but verify"), and verifies the settler signature over the same bytes.

quote_hash is canonicalization-based (URDNA2015), so it is stable across JSON key-order/whitespace normalization and across JSON string-escaping differences. The returned bytes are hash-equivalent to, but not necessarily byte-identical with, what the settler emitted (quotes are stored as JSONB, which normalizes on write). The gateway still never re-serializes the quote through a typed struct (that renormalizes timestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.

fulfillment_confirmation
object

Confirmation details after a payment has been successfully delivered. Contains proof of delivery and transaction details for both source and destination chains.

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.

requested_count
integer

How many settler agents this payment's auction was broadcast to. Absent means unknown, never zero.

Example:

8

decline_summary
object[]

Why the payment drew few or no quotes. Read from the same settler reports as the quote-request endpoints, keyed by this payment, so a payment that failed on an expired quote deadline can say WHY nobody funded it instead of only that nobody did.

Every declining agent is counted exactly once under its most recent reason. Empty means no agent declined against this payment, absent means the breakdown could not be read. A payment awarded out of a quote-request batch was bid on at quote time, so its declines are keyed to that batch and are read from the batch's status endpoint rather than here. As on the quote-request endpoints, the free-form decline detail is never relayed.