Payout lifecycle
A payout is prepared first and committed separately. Creating it returns an immutable instruction for review. Confirming that instruction starts the asynchronous compliance review, transaction controls, settlement, and local bank execution stages.
1. Quote
The quote fixes the sell and buy amounts, currencies, rate, fees, destination corridor, and expiry. The payout must reference an active quote.
2. Preparation and confirmation
Axiym prepares the submitted payment data and returns a payout with status
PENDING_CONFIRMATION. Review its financial terms and final paymentData,
including any mapped fields and normalized controlled values.
Preparation happens in a defined order:
- A saved Party Data Map translates sender and receiver field paths when one is supplied.
- Controlled values across sender, receiver, transaction, and document data are normalized to allowed Axiym values.
- Deterministic schema, baseline, and corridor rules validate the complete result.
If mapping, normalization, or validation fails, no payout is prepared for confirmation.
No funds move and execution does not begin while the payout is awaiting
confirmation. Confirm it before confirmationExpiresAt. Confirmation accepts
the referenced quote, commits the exact prepared instruction, and reserves the
quote's totalPayable in the funding account. The reserved amount cannot fund
another payment. A material change requires a new payout.
3. Compliance review and approval
After confirmation, Axiym performs compliance, risk, and transaction-control review against the exact prepared instruction. This review determines whether the committed payment may proceed; it does not remap or mutate its payment data.
If a payout is rejected at this stage, it is never sent to the local payout provider and its reserved amount is released.
4. Settlement
After approval, settlement converts the reservation into a debit for the sell amount and applicable fee. If the payout ends before settlement, its reserved amount is released back to the funding account's available balance.
Depending on the execution route, external preparation can occur before or after settlement. That sequencing does not change the partner-facing payout lifecycle.
Cancellation after confirmation
Confirmation starts settlement and commits the payment for processing. The Payment API does not provide a cancellation endpoint after confirmation: reversing a settlement requires manual intervention. Contact Axiym promptly if you need help with a confirmed payment. Once the instruction has been submitted to a local payout provider, cancellation is not guaranteed.
5. Local execution
Axiym sends the approved payout through the selected local banking route.
The local provider can accept, reject, complete, or return the payout. Returned payouts require operational review and are not treated as successful completion.
6. Tracking and reconciliation
Use webhooks for timely status notifications and GET /payouts/{payoutId} for
the authoritative current payout resource. Periodically reconcile payouts to
the funding account statement so missed notifications cannot leave records
unresolved.
Failure boundaries
| Point in the lifecycle | Result |
|---|---|
| Quote is invalid when creating the payout | No payout is created. Request a new quote. |
| A field cannot be mapped or a controlled value cannot be normalized | No payout is prepared. Correct the reported field and submit again. |
| Normalized payment data fails deterministic validation | No payout is prepared. Correct the reported fields and submit again. |
| Prepared payout is not confirmed before expiry | The payout becomes EXPIRED; no funds move and no instruction is executed. |
Available balance cannot cover totalPayable at confirmation | Confirmation is not accepted and no amount is reserved. |
| Confirmed payout fails compliance or transaction-control review | The payout is rejected before local execution and its reservation is released. |
| A confirmed payout needs to be stopped | Contact Axiym; the API has no cancellation endpoint because settlement reversal requires manual intervention. |
| Local provider rejects the instruction | The payout ends unsuccessfully after submission. |
| Local provider returns a payout | The outcome requires operational handling and reconciliation. |
Do not infer success from an accepted confirmation response. Continue processing until the payout reaches a terminal outcome.
Use Test payout data to exercise mapping, value normalization, and destination validation without entering this lifecycle.