> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atum.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconciliation

> The identifiers and fields to record for every payment so you can reconcile it without reconstructing it from wallet dashboards — and how to separate Atum fees from gas, swap, and bridge costs.

## 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:

| Field                      | What it is                                                             | Where to find it                                |
| -------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------- |
| `payment_id`               | Atum's identifier for the payment                                      | Gateway submit response; `/status`; `/timeline` |
| `request_id`               | Your idempotency key — reuse it to retry the *same* payment            | You set it on submit; echoed by `/status`       |
| Source tx hash             | The deposit on the source chain                                        | `/timeline`; source-chain explorer              |
| Destination tx hash        | The fulfillment on the destination chain                               | `/timeline`; destination-chain explorer         |
| Source asset + amount      | What left the payer (chain, contract, atomic amount)                   | Your request; `/status`                         |
| Destination asset + amount | What the recipient received                                            | `/status`; settlement receipt header            |
| Quote selected             | The settlement quote the Gateway selected                              | `/timeline`                                     |
| Settlement status          | `pending`, `finalizing`, `completed`, or `failed`, plus any error code | `/status`                                       |
| Timestamps per state       | When it was submitted, quoted, settled                                 | `/timeline`                                     |
| Fees (see below)           | Atum fee, chain gas, and any swap/bridge cost                          | `/timeline`; explorers; provider dashboards     |

<Tip>
  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`.
</Tip>

## Where to find each

Poll the gateway for the authoritative record:

```bash theme={null}
curl -sS "${ATUM_GATEWAY_URL}/v1/payments/${PAYMENT_ID}/status" | python3 -m json.tool
```

```bash theme={null}
curl -sS "${ATUM_GATEWAY_URL}/v1/payments/${PAYMENT_ID}/timeline" | python3 -m json.tool
```

`/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](/get-started/reference/glossary#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](/payment-protocols/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](/get-started/support/troubleshooting).

## Next steps

| Topic                       | Link                                                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| How retries work            | [Idempotency](/payment-protocols/idempotency)                                                                                 |
| Something failing?          | [Troubleshooting](/get-started/support/troubleshooting)                                                                       |
| Supported chains and tokens | [Supported networks](/get-started/reference/supported-networks) · [Supported assets](/get-started/reference/supported-assets) |
| Which environment to target | [Choose an environment](/payment-protocols/environments)                                                                      |