Track a payout
Creation returns 201 Created with status PENDING_CONFIRMATION.
Store the returned paymentId and review the payment before
confirming it.
Confirmation reserves funds and moves the payout to PENDING.
Processing then continues asynchronously; confirmation is not a successful
payout outcome.
Poll the payout
curl \
"https://partner-api.sandbox.axiym.io/api/v1/payouts/$PAYMENT_ID" \
--header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"The payout resource is the authoritative current view. It returns the common
payment document containing the funding account, commercial
terms, prepared payment details, status, and reasonCode when present.
Interpret statuses by phase
| Phase | Statuses | Meaning |
|---|---|---|
| Awaiting your action | PENDING_CONFIRMATION | Review the prepared instruction and confirm it to start processing. No funds are reserved. |
| Processing | PENDING | The payout is moving through review, settlement, or local execution. Keep tracking. |
| On hold | HELD | The payout is temporarily on hold. No action is required unless Axiym requests information. |
| Delivered | COMPLETED | The payout was delivered successfully. Continue handling any later return. |
| Canceled or rejected | CANCELED, REJECTED | The payout was canceled or rejected, including a return after delivery. Retain the reasonCode and reconcile any balance effect. |
Approval, settlement, and submission have no dedicated payout events or
statuses. The published payout events are payout.created, payout.held,
payout.completed, payout.canceled, and payout.rejected.
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. payout.created reports the awaiting-confirmation state; processing
starts only after confirmation. payout.held, payout.completed,
payout.canceled, and payout.rejected report the later status changes, and
a follow-up API read gives you the current complete resource. See the complete
Events reference.
Your webhook handler 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.
Outcomes and later returns
Continue tracking through delivery, cancellation, or rejection. Creation, confirmation, approval, settlement, or submission alone is not proof that the recipient was paid. After completion, keep processing webhooks and reconciling statement movements so that a later return is handled even if its notification is missed.
When reasonCode is present, retain it with the payout. A payout whose funds
were returned after delivery is reported through payout.canceled with a
reasonCode. Retrieve the current payout, retain its updated outcome, and
reconcile the related movements, even if your local record previously showed
COMPLETED.