Skip to main content

​
Overview

A single customer payment usually involves more on-chain movement than the payment itself: the deposit into the settlement vault on the source chain, the settlement on the destination chain, and — behind the scenes — settlement operators 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 — part of the settlement operator’s charge, taken by the settlement vault from the operator’s payout when the deposit is released. Rate and cap: Atum’s fee.
  • What the settlement operator keeps — the rest of its charge, for settling 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, see When a payment is still settling. A new identifier is a new payment.
  • On the acceptance side, key fulfillment on the payment id from the receipt (deliver once).
  • For out-of-band reconciliation (dashboards, ledger jobs), /status and /timeline by payment_id remain authoritative. See Troubleshooting.

​
Next steps