# Track a payout

Use webhooks and polling to follow a payout through processing and its final outcome.

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/track-a-payout

Creation returns `201 Created` with status `PENDING_CONFIRMATION`.
Store the returned `paymentId` and review the payment before
[confirming it](/payment-api/integration-guide/create-a-payout#confirm-the-payout).

Confirmation reserves funds and moves the payout to `PENDING`.
Processing then continues asynchronously; confirmation is not a successful
payout outcome.

## Poll the payout

```sh
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](/payment-api/events).

Your webhook handler must:

1. capture the raw request body;
2. verify the Ed25519 signature;
3. de-duplicate by event `id`;
4. persist or queue the event;
5. return `2xx`; and
6. 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](/payment-api/integration-guide/reconcile-payouts)
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`.