Send money from your merchant balance to a beneficiary's payment instrument. The payout goes through compliance screening and risk evaluation before it is submitted to a rail. See How Anton Evaluates Payouts.
The payout usually comes back in status processing, because screening starts as it is created. It is on_hold when it goes to review. When your own approval policy needs a second person, it moves to pending_approval after screening. Treat created the same way: in progress. The payout moves on asynchronously, and its status changes arrive as payout.* webhook events. Do not poll.
Both source_amount and destination_amount are required. fixed_side (fixed_source or fixed_destination) says which one is authoritative, and the other is recomputed from current corridor pricing. Amounts are decimal strings with at most the currency's precision (2 places for USD, 0 for JPY, 6 for USDC). More is 422 amount_precision_invalid. To pin the fee and rate, call POST /v1/pricing/quotes first and pass its id as quote_id.
A payout that cannot be processed is refused with 422 cannot_be_processed, and the response never says why. A payout your own approval policy blocks is 422 policy_blocked.
Requires an Idempotency-Key header.
Headers
Anton-VersionstringThe API version for this request, a date such as 2026-12-01. Optional. Without it, the request runs on your account's pinned version: the latest version when you created your first OAuth client, or the launch version (2026-12-01) if you have not created one. An unknown value returns 400 invalid_api_version. The header applies to one request and never changes your pinned version; move the pin from the dashboard. It does not apply to webhooks, which follow your pinned version. The response echoes the version used in the Anton-Version header.
"2026-12-01"Idempotency-Keystring · requiredUnique key identifying this operation. Sending the same key twice returns the original response instead of creating a duplicate. Keys are retained for 24 hours.
Body application/json
beneficiary_idstring · requiredinstrument_idstring · requiredMust belong to the beneficiary named above and be active.
source_amountdecimal string · requiredAmount debited from your balance (before fees), at most the source currency's precision.
"1234.56"destination_amountdecimal string · requiredAmount the beneficiary receives, at most the destination currency's precision.
"1234.56"destination_currencystring · requiredUppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.
"USD"methodstring · requiredHow the payout is delivered. Not the same as an Instrument's method (the credential format): this is the rail-family selection.
bank_transferwiresepaswiftachfaster_paymentmobile_moneywalletcardinteraccryptolayer2exchangestablecoinpurposestring · requiredPayment purpose code, used for compliance reporting and corridor-specific rail requirements.
Examples: contractor_payment, supplier_payment, salary, refund.
"contractor_payment"referencestring · requiredYour own reference. Reaches the beneficiary where the rail supports it.
"INV-1042"source_currencystringFunding currency. Defaults to your merchant's default currency.
"USD"rail_typestringHint for rail routing. Anton may override it based on corridor availability.
fiatcryptostablecoinnetworkstringOptional hint for the rail or chain to use.
swiftsepaachfpsrtgsethereumbitcointronsolanapolygonarbitrumoptimismbaseavalanchebsclightningstellarripplefixed_sidestringWhich amount is authoritative. Anton recomputes the other from current corridor pricing.
fixed_sourcefixed_destinationfee_bearerstringWho absorbs the fee. beneficiary reduces the amount credited to them by the fee.
merchantbeneficiaryexternal_idstringYour own identifier for the payee (CRM ID, accounting code), for reconciliation. Returned in
metadata.external_id unless metadata already has that key. Must not contain personal data.
metadataobjectYour own key/value pairs, stored and returned as-is. At most 50 keys; keys up to 40 characters and values up to 500, all strings. On a beneficiary the key block_reason is reserved and is refused with 422. Anton never reads it, never logs or audits it, and never sends it to screening or risk checks, so it is not searchable. Never put personal data in it.
Do not store personal information, account numbers or credentials in metadata. Use the resource's own fields, which are tokenized.
end_user_ipstringIP of the end user who initiated the payout, used for risk signals. Superseded by session.ip: when
both are present, session.ip wins; prefer the session object.
sessionobjectThe end user's session as your edge observed it: the person who started this payout in your product, not your server. Every field is optional, but richer context improves Anton's risk assessment of the payout (IP geolocation and network type, timezone-vs-location consistency, device continuity).
Data-quality issues never fail the payout. Only a syntactically invalid ip is rejected (422). Anything else is accepted and reported in the response's session_quality array so you can fix your integration: a private ip (usually a misconfigured proxy forwarding your own LB address), an unrecognized timezone, a future started_at.
By sending session data you confirm you collected it lawfully from your end user, under your own privacy notice, and are authorized to share it with Anton for fraud prevention and AML transaction-monitoring purposes.
Fields (6)
ipstringThe end user's public IP address (IPv4 or IPv6) as your edge observed it. Must be syntactically valid if present.
"203.0.113.7"user_agentstringThe end user's browser/client User-Agent, verbatim.
accept_languagestringThe end user's Accept-Language header value.
"en-CA"timezonestringThe end user's IANA timezone name.
"America/Toronto"device_hashstringAn opaque device identifier computed by YOU (hash of whatever device signals you collect). Anton treats it as an opaque continuity token and never sees the underlying attributes.
started_atstring (date-time)When the end user's session began (RFC 3339).
quote_idstringA bindable pricing quote returned by POST /v1/pricing/quotes. The payout fee is locked to the
quoted value. The quote must be unexpired, unused, and match the payout's currencies and amount,
otherwise 422 quote_expired, 409 quote_already_used or 422 quote_mismatch.
Responses
201Payout created. Webhooks report its later lifecycle.
idstring · required"pay_01HX8Z9K0M2N3P4Q5R6S7T8UAB"objectstring · requiredpayoutlivemodeboolean · requiredtrue in production, false in the sandbox.
statusstring · requiredWhat you see of a payout's lifecycle. The set is deliberately small and says nothing about why a payout is waiting or refused.
created: accepted; checks have not started.pending_approval: waiting for a second person in your team to approve it (your own approval policy).processing: being checked and prepared, or submitted to the rail.on_hold: held for review. Thestatus_messageis the only thing we say about it. It cannot be cancelled while held.sent: the rail confirmed dispatch.completed: the beneficiary received the funds.returned: the funds came back after being sent.cancelled: cancelled before submission: by you, or by Anton (an approval that expired, or a held payout Anton closed).failed: the payout did not go through, and its status will not change again.failure_codesays what the rail reported, or iscannot_be_processedwhen we could not process the payout (no further detail is given).
Transitions: created to pending_approval, processing or on_hold; pending_approval to
processing or cancelled; processing to on_hold, sent, failed or cancelled; on_hold to
processing, cancelled or failed (only Anton moves an on_hold payout to cancelled; you
cannot); sent to completed, failed or returned. completed,
returned, cancelled and failed are final. Treat a status you do not know as in progress.
createdpending_approvalprocessingon_holdsentcompletedreturnedcancelledfailedstatus_messagestring | null · requiredOur wording for a payout that is on_hold, or failed with failure_code cannot_be_processed.
It never gives a reason. null otherwise.
failure_codestring | null · requiredSet when status is failed, otherwise null. cannot_be_processed means we could not process the
payout and cannot say more. provider_rejected (the generic rail failure), provider_unavailable,
insufficient_funds and beneficiary_not_found are what the rail reported. Treat an unknown code as a
generic failure.
cannot_be_processedprovider_rejectedprovider_unavailableinsufficient_fundsbeneficiary_not_foundbeneficiary_idstring · requiredbeneficiary_namestring | null · requiredThe beneficiary's display name, set on list responses for convenience; null elsewhere.
instrument_idstring · requiredbatch_idstring | null · requiredThe batch that created the payout, if any.
methodstring · requiredHow the payout is delivered. Not the same as an Instrument's method (the credential format): this is the rail-family selection.
bank_transferwiresepaswiftachfaster_paymentmobile_moneywalletcardinteraccryptolayer2exchangestablecoinrail_typestring · requiredfiatcryptostablecoinnetworkstring | null · requiredsource_amountdecimal string · requiredDecimal amount as a string, never a float. Up to 12 whole digits.
"1234.56"source_currencystring · requiredUppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.
"USD"destination_amountdecimal string · requiredDecimal amount as a string, never a float. Up to 12 whole digits.
"1234.56"destination_currencystring · requiredUppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.
"USD"exchange_ratestring | null · requiredSource-to-destination rate; null on a same-currency payout.
feedecimal string · requiredDecimal amount as a string, never a float. Up to 12 whole digits.
"1234.56"fee_currencystring · requiredUppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.
"USD"fee_bearerstring · requiredmerchantbeneficiaryfixed_sidestring · requiredfixed_sourcefixed_destinationfee_finalizedboolean · requiredWhether fee is the final fee confirmed by the rail.
total_debiteddecimal string · requiredTotal drawn from your balance (source_amount plus fee plus buffer while processing).
"1234.56"total_debited_currencystring · requiredUppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.
"USD"buffer_amountdecimal string · requiredCross-currency rate buffer held while processing, released on settlement.
"1234.56"buffer_currencystring | null · requiredCurrency of buffer_amount; null when no buffer applies (the amount is then zero).
wallet_addressstring | null · requiredDestination wallet address. Crypto and stablecoin payouts only.
token_contractstring | null · requiredToken contract address. Stablecoin payouts only.
token_symbolstring | null · required"USDC"transaction_hashstring | null · requiredOn-chain transaction hash, once sent. Crypto and stablecoin payouts only.
block_confirmationsinteger | null · requiredConfirmations observed so far.
required_confirmationsinteger | null · requiredConfirmations needed before the payout is completed.
network_feestring | null · requiredNetwork (gas) fee, deducted from the settlement and not from your balance.
network_fee_currencystring | null · requiredcreated_bystring | null · requiredThe user (usr_...) in your team who created the payout in the dashboard; null for payouts
created with programmatic credentials and batches. The creator can never approve their own payout.
purposestring · requiredreferencestring · requiredapproved_atstring (date-time) | null · requiredprocessed_atstring (date-time) | null · requiredWhen the payout was submitted to the rail.
completed_atstring (date-time) | null · requiredfailed_atstring (date-time) | null · requiredcancelled_atstring (date-time) | null · requiredriskobject | null · requiredThe payout's risk score and tier. Always present: null while the payout has no score, and null for a
payout that is on_hold or failed.
deliveryobject | null · requiredDelivery-time context for the payout. Always present: null when the corridor has no estimate, when the
payout is not in flight, and for a payout that is on_hold or failed. It is populated on retrieve
(GET /v1/payouts/{id}), on create and cancel, and in webhook events (the same object, computed at that moment); it is null in lists, where computing it per payout would cost a query each.
session_qualityarray of string | null · requiredAlways present. On POST /v1/payouts, the data-quality flags found in the request's session object
(non-blocking: the payout was created; fix the flagged fields to improve risk-signal quality); null
when there are none and on every other response and event.
metadataobject · requiredYour own key/value pairs, stored and returned as-is. At most 50 keys; keys up to 40 characters and values up to 500, all strings. On a beneficiary the key block_reason is reserved and is refused with 422. Anton never reads it, never logs or audits it, and never sends it to screening or risk checks, so it is not searchable. Never put personal data in it.
Do not store personal information, account numbers or credentials in metadata. Use the resource's own fields, which are tokenized.
created_atstring (date-time) · requiredRFC 3339 / ISO 8601 timestamp in UTC.
"2026-04-15T14:30:00Z"updated_atstring (date-time) · requiredRFC 3339 / ISO 8601 timestamp in UTC.
"2026-04-15T14:30:00Z"400The request body could not be parsed or contains unknown fields, its `Content-Type` is not `application/json` (`invalid_content_type`), or t
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."401Missing, expired or invalid credentials (access token or DPoP proof). Carries `WWW-Authenticate`.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."403The account capability or credential scope the call needs is missing.
The account capability or credential scope the call needs is missing.
capability_required: the merchant account does not hold the required capability (for example, an AI-compliance-only account calling a payout endpoint). insufficient_scope: the account holds it, but this credential was created without the matching scope. Effective access is always scopes ∩ capabilities. A sandbox credential used against production is key_environment_mismatch.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."404`resource_missing`: `beneficiary_id` or `quote_id` names no beneficiary or pricing quote of yours.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."409`idempotency_in_flight` (another request with this key is still running) or `quote_already_used`.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."422Well-formed but refused. Codes: `validation_error` (a field fails validation; `details` lists every one, including `metadata` over its limit
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."429Rate limit exceeded. See `Retry-After`. The `X-RateLimit-*` headers are on every authenticated API response, not only on 429s; they are docu
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."500Something went wrong on our end (`api_error`: 500 `internal_error`, 502 `upstream_error`, 503 `service_unavailable`). The message is always
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."