Skip to main content

​
Overview

Your funds sit in the settlement vault on the source chain until delivery is proven. If the payment is not delivered, the refund returns them to the wallet they came from. You never need to pay again to get your money back. While a refund is in progress, do not start a new payment for the same purchase.

​
How a refund happens

​
When a refund can start

A refund starts after the delivery deadline passes without a delivery. Atum then waits a few more minutes, and until the destination chain has made those blocks final, so it can be sure no payout landed. Refunds are not instant: plan for the delivery deadline, plus a few minutes, plus the destination chain’s time to finality. That is seconds on some chains and tens of minutes on Ethereum and its rollups. A shorter delivery deadline gets your funds back sooner. See Choosing a delivery deadline.

​
How a refund ends

A refund ends in one of two ways:
  1. The settlement operator returns your funds. This is the usual case. The status goes from refunding to refunded, and you do nothing.
  2. You submit the refund yourself. If the settlement operator does not return your funds, Atum signs the refund for you and the status becomes refund_available. Submit it as shown in Getting your funds back yourself. The status becomes refunded once it lands.
What each status means, and what it can turn into, is on Payment status. In short:
  • refunding: keep polling /status. Do not pay again.
  • refund_available: submit the refund yourself. Do not pay again.
  • refunded: final. To try the purchase again, use a new request_id.

​
A failed payment with a deposit

failed is not a refund status. A payment can fail before or after your funds reach the settlement vault. If a failed payment has transactions.deposit set, your funds went into the vault before it failed.
  • The vault can only return them to you, or pay the settlement operator after a verified delivery.
  • The settlement operator normally refunds them after the delivery deadline. The status stays failed and shows no refund fields, so look for the refund on the source chain.
  • Reconcile by payment_id before you pay again. If your funds have not come back, contact Atum support with the payment_id.

​
Why it was refunded

A payment that is refunding, refund_available or refunded can carry refund_reason. It says why the settlement operator gave up, using the same shape as error (code, message). It describes the settlement operator’s problem, not your payment. Ignore its retry_classification and request_id_reusable, and act on status.

​
Getting your funds back yourself

When the status is refund_available, GET /v1/payments/{paymentId}/status returns refund_signature:
Send the refund to the same settlement vault your payment was deposited into. That is the escrow_contract_address in your payment request, which you took from GET /v1/defaults (escrow_contract).
message_prehash is EIP-712 typed data. Its message is the refund details, and its domain.verifyingContract is the settlement vault.Call the vault’s refund function with message as the refund details and signature as the refund signature.
Good to know:
  • Anyone can submit it, but the vault only ever pays the original payer.
  • On Solana, whoever submits it gets back the rent of the accounts the refund closes. If your token account no longer exists, the submitter pays to open it.
  • If the settlement operator delivers late and is paid first, the refund no longer goes through. The payment then ends as completed.
Until someone submits the refund, your funds stay in the settlement vault. Submitting it yourself is the surest way to get them back.

​
Paying with x402 or MPP

x402 and MPP report the refund statuses through their own responses: In both, the payment ID and its current status come with the response (extensions.atum.state on x402, state on MPP). If the state is refund_available, read refund_signature from GET /v1/payments/{paymentId}/status and submit it as shown above. Do not pay again with a new purchase identifier. For refunding and refunded, the usual retry rules apply: When a payment is still settling.

​
Finding the refund on chain

When the refund lands, /status shows it in transactions.refund. Use that hash on the source chain explorer and in your reconciliation records. It can be missing when the refund transaction is not known.

​
Next steps