Anton.Docs
Dashboard (opens in a new tab)

Cancel a payout

POST/v1/payouts/{id}/cancelIdempotency-Key required

Cancel a payout that has not been submitted to a rail. You can cancel while the status is created or pending_approval, and while it is processing early on, up to the point it is submitted to the rail. The response does not show that point, so a processing payout may or may not be cancellable.

A payout that is on_hold cannot be cancelled until the hold ends (409 payout_on_hold). One that is already past submission, or that is sent, completed, returned, cancelled or failed, is 409 payout_not_cancellable. So is one that failed with cannot_be_processed, always with the same wording whatever the reason. The request takes no body.

On success, any debited source funds (source amount, fee and buffer) return to your balance.

Requires an Idempotency-Key header.

Path parameters

idstring · required

The payout ID (pay_...).

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.

Responses

200The cancelled payout.
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."
404The resource does not exist, or belongs to a different merchant.
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."
409State conflict: `payout_not_cancellable` (the payout is past the point of cancelling, or failed), `payout_on_hold` (the payout is under revi
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."
422`idempotency_key_reused`: you used the same `Idempotency-Key` with a different request body. Send a new key for a new request.
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) ↗