> ## Documentation Index > Fetch the complete documentation index at: https://docs.antonpayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a Payout > The full payout flow — beneficiary, instrument, economics, corridors, and the state machine your integration should respond to. **Editability note:** this guide was drafted against the OpenAPI spec. If the product/engineering team hasn't validated it against a recent end-to-end trace, flag anything that reads off and edit the relevant section — each H2 below is self-contained. A payout is a single payment from your merchant balance to a beneficiary's payment instrument. This guide walks through everything you need to know to send one in production: the data model, the fields that matter, the state machine, and how your integration should respond to each state. For a 5-minute sandbox walkthrough, start with the [Quickstart](/quickstart). This guide assumes you've already done that and need to build the real thing. ## The data model Three entities come together on every payout: * **[Beneficiary](/api-reference/beneficiaries/get-beneficiary)** — who you're paying. Identity only; PII is tokenized on creation. * **[Instrument](/api-reference/instruments/get-instrument)** — where the money goes. Bank account, wallet, or card, attached to a beneficiary. Credentials are tokenized. * **[Payout](/api-reference/payouts/get-payout)** — the single payment. Links a beneficiary and one of their instruments to an amount, currency, and rail. Create them in that order. Beneficiaries can have many instruments; one payout uses exactly one instrument. ## Economics: source vs dest amounts Every payout has two amounts: * `source_amount` — what's debited from your merchant balance in your source currency. * `dest_amount` — what the beneficiary receives in their destination currency. For same-currency payouts these are equal. For cross-currency payouts, Anton computes the other side using the current corridor pricing. The `fixed_side` field tells Anton which amount is authoritative: * `fixed_dest` (default) — beneficiary receives exactly `dest_amount`; Anton computes `source_amount` including FX and fees. * `fixed_source` — merchant pays exactly `source_amount`; Anton computes how much the beneficiary receives after FX and fees. `fee_bearer` controls who absorbs the fee: * `merchant` (default) — fee is added on top of `source_amount`. * `beneficiary` — fee is deducted from `dest_amount`, so the beneficiary receives less than the stated amount. ## Corridors, methods, and rails A **corridor** is a `(currency, country, method, network)` combination Anton can deliver through. Before attempting a payout, verify the corridor is enabled on your account: ```bash theme={} curl "https://api.antonpayments.dev/v1/corridors?currency=EUR&country=DE" \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" ``` The `method` field on `POST /v1/payouts` selects the delivery method. For fiat: * `faster_payment` — UK Faster Payments * `sepa` — SEPA Credit Transfer (EUR) * `ach` — US ACH * `swift` — SWIFT international wire * `wire` — generic domestic wire * `bank_transfer` — generic bank transfer (rail picks based on corridor) * `mobile_money` — M-Pesa, MTN, etc. For crypto/stablecoin, see [Crypto & Stablecoin Payouts](/guides/crypto-payouts). `rail_type` (`fiat`, `crypto`, or `stablecoin`) is a hint Anton may override based on corridor availability. ## Purpose and reference Two required fields that serve different audiences: * `purpose` — a compliance-facing payment-purpose code. Examples: `contractor_payment`, `supplier_payment`, `salary`, `refund`, `services`, `goods`. Used for reporting and some rails require it. * `reference` — your own free-form string, up to 100 chars. Appears on the beneficiary's statement where the rail supports it. Use your invoice or order number so both sides can reconcile. ## Idempotency `POST /v1/payouts` requires an `Idempotency-Key` header. Derive it from your own business data so retries after a network failure converge on the same payout: ``` Idempotency-Key: payout-{invoice_id}-{beneficiary_id} ``` If you retry with the same key, Anton returns the original response and sets `X-Idempotent-Replayed: true`. Different bodies with the same key return `409 idempotency_conflict`. See [Idempotency](/api-reference/idempotency) for details. ## The state machine Payouts move through a 13-state machine. The full detail is in [How Anton Evaluates Payouts](/how-anton-evaluates-payouts); the short version: | State | Meaning | What to do | | ------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- | | `created` | Payout record exists. Next: screening. | No action. | | `pending_screening` | OFAC + velocity + engine scoring running. | No action. Transient. | | `pending_approval` | Clear to submit; waiting for maker-checker if configured. | No action. | | `approved` | Ready for the rail. | No action. | | `processing` | Submitted to the rail. | Surface "in flight" in your UI. | | `sent` | Rail confirmed dispatch. | Surface "sent" in your UI. | | `completed` | Funds delivered and settled. | Mark the payout done in your system. | | `failed` | Rail returned a hard failure. | Review failure reason; may retry with a different instrument. | | `returned` | Funds were returned after send. | Handle the return in your accounting. | | `screening_failed` | Sanctions or compliance block. | Do NOT retry with same beneficiary. | | `velocity_blocked` | Merchant velocity rule rejected. | Wait for velocity window to reset, or request a higher threshold. | | `manual_review` | Held for human review — usually Anton Engine flagged risk. | Treat as a normal "pending" state; can take minutes to hours. | | `cancelled` | Cancelled before rail submission. | Final. | ## Subscribe to webhooks — don't poll Every state transition fires a `payout.*` event. Subscribe once via `POST /v1/webhooks` and handle the events you care about: * `payout.completed` — funds delivered * `payout.failed`, `payout.returned` — terminal failure paths * `payout.screening_failed`, `payout.velocity_blocked` — compliance/risk blocks * `payout.cancelled` — operator or API cancellation Polling `GET /v1/payouts/{id}` works in development but wastes rate-limit budget at scale and misses transitions. ## Cancelling a payout You can cancel a payout that has not yet been submitted to a rail — from `created`, `pending_screening`, `pending_approval`, `pending_engine_review`, or `manual_review`: ```bash theme={} curl https://api.antonpayments.dev/v1/payouts/$PAYOUT_ID/cancel \ -X POST \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "Idempotency-Key: cancel-$PAYOUT_ID" \ -H "Content-Type: application/json" \ -d '{"reason": "beneficiary requested change of account"}' ``` Once a payout reaches `processing`, the rail has it — cancellation is no longer possible via the API. Contact support if you need to halt an in-flight payout. On successful cancellation, the debited funds (source amount, fee, and any FX buffer) are released back to your balance. ## What can go wrong Your merchant balance in the source currency can't cover `source_amount + fee + buffer`. Top up the balance or reduce the payout. The requested `(source_currency, dest_currency, country, method)` isn't active on your account. Call `GET /v1/corridors` to see active ones, or contact support to enable a new corridor. The ID doesn't exist or belongs to a different merchant. Double-check the ID, including prefix (`ben_...`, `ins_...`). The instrument is archived, disabled, or its method/currency doesn't match the payout. Instruments are scoped to a single country + method at creation. Honor `Retry-After` and back off. See [Rate Limits](/api-reference/rate-limits). ## Next steps Dedup, update PII, archive, restore. Subscription, signing, delivery semantics. Network selection, finality, memo/tag fields. Lockable quotes and cross-currency payouts.