# Reconcile payouts

Join payout resources, webhook events, partner references, and funding account statement entries.

Product: Payment API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/payment-api/integration-guide/reconcile-payouts

Use payouts as the business view of outgoing payments and account statements as
the ledger view of the balance movements that fund them.

Creation does not reserve funds or create a statement debit. Confirmation
creates a reservation, not a posted debit. The payout's
`sourceAmount` is posted as a debit when settlement occurs. If the payout ends
before settlement, the reservation is released without becoming that settled
debit.

## Use the partner context

| Resource          | Retrieve through the authenticated partnership |
| ----------------- | ---------------------------------------------- |
| Payout            | `GET /payouts/{paymentId}`                     |
| Account statement | `GET /accounts/{accountId}/statement`          |

Use only related resources returned to the same integration.

## Retrieve the account statement

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/accounts/$ACCOUNT_ID/statement?from=2026-08-01&to=2026-08-31&first=100" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

`from` and `to` are inclusive UTC posting dates, not payout creation dates.
Pass `pageInfo.endCursor` as `after` while `pageInfo.hasNextPage` is true,
keeping the same period and filters.

The statement is self-checking:

```text
openingBalance + totalCredited - totalDebited = closingBalance
```

## Join the records

Use each identifier for its intended purpose:

| Identifier                                    | Purpose                                                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `paymentId`                                   | Retrieve and identify the Axiym payout.                                                                 |
| `externalReference`                           | Join the payout to your business transaction.                                                           |
| `paymentDataMapId`                            | Identify the field and value rules used to create a mapped payout. Retain it from the creation request. |
| `relatedResourceType` and `relatedResourceId` | For `PAYOUT` entries, match `relatedResourceId` to `paymentId`.                                         |
| Statement `entryId`                           | De-duplicate a ledger entry when replaying statement pages or periods.                                  |
| Event `id`                                    | De-duplicate one webhook event.                                                                         |
| `X-Request-Id`                                | Investigate one HTTP attempt.                                                                           |
| `Idempotency-Key`                             | Determine whether a state-changing request is new or a retry.                                           |

Store these separately rather than reusing one identifier for all purposes.

Persist `paymentId`, `accountId`, `externalReference`, commercial terms, and
the latest observed payout state when each payout is created. The
list-payouts endpoint can filter by account, `externalReference`, or status,
but it does not provide an updated-time range filter.

For mapped payouts, also persist the `paymentDataMapId` used for that payout
and the map's `contentHash`. The payout response does not return the map ID.
Keep this association per payout when switching your integration to a newer
map, so historical payments remain traceable to their original rules.
Archived maps can still be [retrieved by identifier](/payment-api/api-reference/payment-data-maps/getPaymentDataMap).

## Recommended reconciliation loop

1. Retrieve every page of the funding account statement for the posting
   period. De-duplicate entries by `entryId` before applying balance effects.
2. For entries with `relatedResourceType: PAYOUT`, use `relatedResourceId` to
   fetch the current payout. Include payouts previously recorded as
   `COMPLETED`: a new movement may relate to a later return.
3. Also refresh locally pending or unresolved payouts, including those with
   no statement entry. If rebuilding local state, paginate through the payout
   list without assuming a time-range filter.
4. Match settlement entries with `type: DEBIT` to the payout's `sourceAmount`,
   comparing both `amount` and `currency` with the retained payment record.
5. Reconcile related `CREDIT` entries separately, including movements associated
   with returns. Amounts are positive; `type` supplies the direction. Do not
   compare a credit as though it were the original settlement debit.
6. Escalate missing expected settlement debits, distinct entries that appear
   to duplicate a movement, amount or currency mismatches, and returned
   payouts for operational review.

A payout awaiting confirmation has no reservation or settlement debit. Do not
treat the absence of a statement entry as an error for an unconfirmed or
unsettled payout.

Run reconciliation even when webhooks appear healthy. It is the recovery path
for notifications your system did not receive or process.

Checkpoint statement cursors or completed UTC date ranges only after every page
has been processed. Keep the previous period available for replay so a failed
job can resume without creating gaps.