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
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:
openingBalance + totalCredited - totalDebited = closingBalanceJoin 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.
Recommended reconciliation loop
- Retrieve every page of the funding account statement for the posting
period. De-duplicate entries by
entryIdbefore applying balance effects. - For entries with
relatedResourceType: PAYOUT, userelatedResourceIdto fetch the current payout. Include payouts previously recorded asCOMPLETED: a new movement may relate to a later return. - 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.
- Match settlement entries with
type: DEBITto the payout'ssourceAmount, comparing bothamountandcurrencywith the retained payment record. - Reconcile related
CREDITentries separately, including movements associated with returns. Amounts are positive;typesupplies the direction. Do not compare a credit as though it were the original settlement debit. - 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.