Track a payout
Payout processing is asynchronous after confirmation. Store the returned
payoutId and continue tracking after the confirmation request returns
202 Accepted.
Confirmation is a commitment to process the exact prepared instruction. It reserves funds, but it is not a successful payout outcome.
Poll the payout
curl \
"https://partner-api.sandbox.axiym.io/api/v1/payouts/$PAYOUT_ID" \
--header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"The payout resource is the authoritative current view. It contains the quote, funding account, partner reference, financial amounts, status, and failure details when present.
Interpret statuses by phase
| Phase | Statuses | Meaning |
|---|---|---|
| Prepared | PENDING_CONFIRMATION | Review is still possible. Nothing is reserved or submitted. |
| Processing | PROCESSING, APPROVED, SETTLED, SUBMITTED | The payout is confirmed and moving through review, settlement, or local execution. Keep tracking. |
| Successful terminal | COMPLETED | The payout completed through the local route. |
| Unsuccessful terminal | REJECTED, FAILED, RETURNED, CANCELED, EXPIRED | The payout did not complete successfully. Retain failure detail and reconcile any balance effect. |
Do not derive an internal state machine from event arrival order. Use the current payout resource when deciding which actions remain valid.
Receive webhook events
Subscribe an HTTPS endpoint and process the payout events relevant to your
workflow. Events such as payout.approved, payout.settled,
payout.completed, and payout.failed give you timely signals, while a
follow-up API read gives you the current complete resource. See the complete
Events reference.
Your receiver must:
- capture the raw request body;
- verify the Ed25519 signature;
- de-duplicate by event
id; - persist or queue the event;
- return
2xx; and - fetch the payout before taking an action that depends on current state.
Return 2xx after the event has been durably accepted, not after all downstream
business processing has completed. Process slow work asynchronously.
Do not depend on delivery order
Webhook delivery is at-least-once. Duplicate, delayed, or out-of-order events can occur. Never move your internal state backward solely because an older event arrived later.
Terminal outcomes
Continue tracking until a terminal status is reached. An accepted confirmation request, approval, settlement, or provider submission alone is not proof that the receiver was paid.
When failure details are present, retain their code and message with the
payout. Returned payouts require operational handling and reconciliation; do
not represent them as completed payments in your product.