Overview
A single customer payment usually involves more on-chain movement than the payment itself: the escrow deposit on the source chain, the settlement on the destination chain, and — behind the scenes — settlers moving and sometimes converting funds across chains. If you only keep the final response, reconstructing what happened later means digging through several wallet dashboards and block explorers.
Record a small set of identifiers as each payment happens so you can reconcile it from your own logs.
What to record
Capture these for every payment, on success and on failure:
The examples surface the settlement result for you: x402 returns it in the PAYMENT-RESPONSE header, and MPP returns a Payment-Receipt header on the 200. Log that receipt alongside your payment_id.
Where to find each
Poll the gateway for the authoritative record:
/status gives you the current state and final amounts; /timeline gives you the per-state history and the transaction hashes on both chains. Use those hashes to confirm the movement on the source and destination explorers.
Separating the fees
The amount that leaves the payer is larger than the amount the recipient receives, and the difference is not a single fee. Keep two cost categories distinct:
- Atum fee — the Atum smart contract charges a fee of 2 basis points of the token amount, with a limit of $250. This is retained by the smart contract when the settler withdraws the payer’s funds.
- Settler fee — the remainder of the deposit overage is withdrawn by the settler. This constitutes their fee for having settled the payment.
Attributing every cost to “the payment” overstates Atum’s fee. Reconcile each category from its own source.
Idempotency and retries
- To collect a payment that is still settling, re-attempt the same purchase (same purchase identifier / derived
request_id). A new identifier is a new payment.
- Do not poll the gateway inside the payer’s open HTTP request. Pending means re-attempt; terminal failure means a new identifier. See Idempotency.
- On the acceptance side, key fulfillment on the receipt’s
payment_id, not on the request — a reused purchase identifier replays the first receipt.
- For out-of-band reconciliation (dashboards, ledger jobs),
/status and /timeline by payment_id remain authoritative. See Troubleshooting.
Next steps
