After submission

A payment_id means the gateway accepted your payment. It does not mean the funds have arrived. This page shows how to follow a payment to the end and what to do if it fails.

Payment status

`status`	Meaning	Final	Can become
`pending`	Accepted and in progress. Quotes are being collected, or your funds are being moved into the settlement vault. Nothing has reached the recipient yet.	No	any other status
`finalizing`	The payout to your recipient is mined on the destination chain, waiting for that chain to make it final.	No	`completed`, `failed`, `refunding`, `refund_available`, `refunded`
`completed`	Delivered and final on the destination chain.	Yes	—
`failed`	Did not complete. `error` says why. If `transactions.deposit` is set, your funds went into the settlement vault: see A failed payment with a deposit.	Yes	—
`refunding`	Not delivered. Any funds you deposited are on their way back from the settlement vault.	No	`completed`, `failed`, `refund_available`, `refunded`
`refund_available`	Not delivered. The refund is ready, but your funds are still in the settlement vault until it is submitted.	No	`completed`, `refunded`
`refunded`	Your funds are back.	Yes	—

The usual paths: finalizing is not final. If you act on it, for example to release goods, you accept the small risk that the payout is reversed. You can also open the payout transaction (transactions.fulfillment) in the destination chain’s block explorer and wait for the number of confirmations you are comfortable with. How long finalizing lasts, and what Atum waits for on each chain, is on Finality. refunding and refund_available are not final either. A late delivery can still end the payment as completed. Refunds explains who returns your funds and how to submit a refund yourself.

Track a payment

POST /v1/payments keeps the connection open for up to 30 seconds and answers as soon as the payment is finalizing, completed or failed. If it is still pending, poll the status every few seconds until it is completed, failed or refunded. If it is refund_available, submit the refund yourself.

HTTP
SDK
CLI

curl -sS "https://payment-gw.production-testnet.atum.xyz/v1/payments/${PAYMENT_ID}/status"

const status = await client.payments.getPaymentStatus({ paymentId });

payment-status --gateway https://payment-gw.production-testnet.atum.xyz "$PAYMENT_ID"

What the status response contains

Field	What it tells you
`status`, `error`	Where the payment is, and why it failed if it did.
`transactions.deposit`	Your funds moving into the settlement vault on the source chain.
`transactions.fulfillment`	The payout to your recipient on the destination chain.
`transactions.refund`	Your funds returning from the settlement vault, on a refunded payment.
`refund_signature`, `refund_reason`	On a payment that was not delivered: the refund to submit yourself, and why the settlement operator gave up. See Refunds.
`requested_count`, `decline_summary`	How many settlement operators were asked, and why any of them declined.

Each entry in transactions has the transaction hash, the chain, and the block once it is mined. A completed payment always has both transactions.deposit and transactions.fulfillment. Read every transaction from transactions. Full shape: Get payment status.

When a payment fails

Read error.code first, then decline_summary. Deadlines lists every deadline error and what to change. For example, a quote window that ends after the operators’ quotes would expire:

{
  "payment_id": "0x…",
  "status": "failed",
  "error": {
    "code": "NO_QUOTES_RECEIVED",
    "message": "No settlement quotes were received within the auction window. This request_id is spent, so a new attempt needs a new one.",
    "retry_classification": "RETRY_WITH_NEW_IDENTIFIER"
  },
  "requested_count": 2,
  "decline_summary": [
    { "reason": "QUOTE_WINDOW_TOO_LONG", "count": 2 }
  ]
}

Both settlement operators declined. Send a new payment with a new request_id and a shorter quote window.

Retry without paying twice

Not sure it was accepted? Send the same signed request again: if the gateway already accepted it, you get the original payment back instead of a second one. What to do for each status: Retrying by status.

Next steps

Topic	Guide
The deadlines and the errors they cause	Deadlines
Symptom-first diagnosis	Troubleshooting
Reconcile a payment	Reconciliation

Overview

Start building

Payment lifecycle

Support

Reference

Payment status

Track a payment

What the status response contains

When a payment fails

Retry without paying twice

Next steps

​Payment status

​Track a payment

​What the status response contains

​When a payment fails

​Retry without paying twice

​Next steps

Payment status

Track a payment

What the status response contains

When a payment fails

Retry without paying twice

Next steps