Anton.Docs
Dashboard (opens in a new tab)

Create a payout

POST/v1/payoutsIdempotency-Key required

Walked through inPay out in stablecoinSend a payoutSend your first payout

Example

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-Versionstring

The 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.

Example: "2026-12-01"
Idempotency-Keystring · required

Unique 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 · required
instrument_idstring · required

Must belong to the beneficiary named above and be active.

source_amountdecimal string · required

Amount debited from your balance (before fees), at most the source currency's precision.

Example: "1234.56"
destination_amountdecimal string · required

Amount the beneficiary receives, at most the destination currency's precision.

Example: "1234.56"
destination_currencystring · required

Uppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.

Example: "USD"
methodstring · required

How the payout is delivered. Not the same as an Instrument's method (the credential format): this is the rail-family selection.

bank_transferwiresepaswiftachfaster_paymentmobile_moneywalletcardinteraccryptolayer2exchangestablecoin
purposestring · required

Payment purpose code, used for compliance reporting and corridor-specific rail requirements. Examples: contractor_payment, supplier_payment, salary, refund.

Example: "contractor_payment"
referencestring · required

Your own reference. Reaches the beneficiary where the rail supports it.

Example: "INV-1042"
source_currencystring

Funding currency. Defaults to your merchant's default currency.

Example: "USD"
rail_typestring

Hint for rail routing. Anton may override it based on corridor availability.

fiatcryptostablecoin
networkstring

Optional hint for the rail or chain to use.

swiftsepaachfpsrtgsethereumbitcointronsolanapolygonarbitrumoptimismbaseavalanchebsclightningstellarripple
fixed_sidestring

Which amount is authoritative. Anton recomputes the other from current corridor pricing.

fixed_sourcefixed_destination
fee_bearerstring

Who absorbs the fee. beneficiary reduces the amount credited to them by the fee.

merchantbeneficiary
external_idstring

Your 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.

metadataobject

Your 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_ipstring

IP 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.

sessionobject

The 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)
ipstring

The end user's public IP address (IPv4 or IPv6) as your edge observed it. Must be syntactically valid if present.

Example: "203.0.113.7"
user_agentstring

The end user's browser/client User-Agent, verbatim.

accept_languagestring

The end user's Accept-Language header value.

Example: "en-CA"
timezonestring

The end user's IANA timezone name.

Example: "America/Toronto"
device_hashstring

An 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_idstring

A 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
Example: "pay_01HX8Z9K0M2N3P4Q5R6S7T8UAB"
objectstring · required
payout
livemodeboolean · required

true in production, false in the sandbox.

statusstring · required

What 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. The status_message is 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_code says what the rail reported, or is cannot_be_processed when 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_holdsentcompletedreturnedcancelledfailed
status_messagestring | null · required

Our 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 · required

Set 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_found
beneficiary_idstring · required
beneficiary_namestring | null · required

The beneficiary's display name, set on list responses for convenience; null elsewhere.

instrument_idstring · required
batch_idstring | null · required

The batch that created the payout, if any.

methodstring · required

How the payout is delivered. Not the same as an Instrument's method (the credential format): this is the rail-family selection.

bank_transferwiresepaswiftachfaster_paymentmobile_moneywalletcardinteraccryptolayer2exchangestablecoin
rail_typestring · required
fiatcryptostablecoin
networkstring | null · required
source_amountdecimal string · required

Decimal amount as a string, never a float. Up to 12 whole digits.

Example: "1234.56"
source_currencystring · required

Uppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.

Example: "USD"
destination_amountdecimal string · required

Decimal amount as a string, never a float. Up to 12 whole digits.

Example: "1234.56"
destination_currencystring · required

Uppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.

Example: "USD"
exchange_ratestring | null · required

Source-to-destination rate; null on a same-currency payout.

feedecimal string · required

Decimal amount as a string, never a float. Up to 12 whole digits.

Example: "1234.56"
fee_currencystring · required

Uppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.

Example: "USD"
fee_bearerstring · required
merchantbeneficiary
fixed_sidestring · required
fixed_sourcefixed_destination
fee_finalizedboolean · required

Whether fee is the final fee confirmed by the rail.

total_debiteddecimal string · required

Total drawn from your balance (source_amount plus fee plus buffer while processing).

Example: "1234.56"
total_debited_currencystring · required

Uppercase currency or asset code, ISO 4217 for fiat (USD) and the published asset code for stablecoins and crypto (USDC). GET /v1/currencies lists them.

Example: "USD"
buffer_amountdecimal string · required

Cross-currency rate buffer held while processing, released on settlement.

Example: "1234.56"
buffer_currencystring | null · required

Currency of buffer_amount; null when no buffer applies (the amount is then zero).

wallet_addressstring | null · required

Destination wallet address. Crypto and stablecoin payouts only.

token_contractstring | null · required

Token contract address. Stablecoin payouts only.

token_symbolstring | null · required
Example: "USDC"
transaction_hashstring | null · required

On-chain transaction hash, once sent. Crypto and stablecoin payouts only.

block_confirmationsinteger | null · required

Confirmations observed so far.

required_confirmationsinteger | null · required

Confirmations needed before the payout is completed.

network_feestring | null · required

Network (gas) fee, deducted from the settlement and not from your balance.

network_fee_currencystring | null · required
created_bystring | null · required

The 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 · required
referencestring · required
approved_atstring (date-time) | null · required
processed_atstring (date-time) | null · required

When the payout was submitted to the rail.

completed_atstring (date-time) | null · required
failed_atstring (date-time) | null · required
cancelled_atstring (date-time) | null · required
riskobject | null · required

The 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 · required

Delivery-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 · required

Always 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 · required

Your 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) · required

RFC 3339 / ISO 8601 timestamp in UTC.

Example: "2026-04-15T14:30:00Z"
updated_atstring (date-time) · required

RFC 3339 / ISO 8601 timestamp in UTC.

Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
401Missing, expired or invalid credentials (access token or DPoP proof). Carries `WWW-Authenticate`.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗