Initiate a withdrawal

post

https://api.checker.finance/v1/payments/withdrawals

Send a payout from an account to a beneficiary on one rail. Returns 202; poll GET /withdrawals/{id} until the status is COMPLETED, FAILED, or CANCELLED.

On the CRYPTO, ACH, FEDWIRE, and SWIFT rails the beneficiary is sent exactly amount and the payout fee (fee_amount) is debited from the account in addition to it; total_amount reports the full debit (amount + fee_amount) once the fee is known. Before submitting, the available balance (net of in-flight withdrawals) is checked against amount plus the estimated fee where the fee can be estimated: a shortfall is rejected synchronously with 400 INSUFFICIENT_FUNDS and a details object (fee_amount, fee_currency, required_amount, available_amount), and no withdrawal is created — top up and retry, with the same Idempotency-Key if you like. If the balance drops between that check and submission, the payout is returned 202 with status: FAILED and reason_code: INSUFFICIENT_FUNDS. Quote-driven payouts are checked on amount alone (the fee is priced into the quote). On CHINA_OFFRAMP, amount is the quote's source_amount (the full debit, so total_amount equals amount) and the beneficiary receives the quote's target_amount.

A CRYPTO payout is funded from the account of the asset being sent: the beneficiary's payment_details.currency must equal the account's currency, otherwise 400 VALIDATION_ERROR. CRYPTO is not available on a fiat account (400 RAIL_NOT_AVAILABLE).

The beneficiary's payment_details must carry an identifier that settles on the requested rail, otherwise 400 VALIDATION_ERROR: SWIFT needs swift_code; ACH, FEDWIRE, RTP, and FEDNOW need routing_number; SEPA and SEPA_INSTANT need iban; FASTER_PAYMENTS and CHAPS need iban or a SORT_CODE entry in bank_routing_codes. A wallet beneficiary (wallet_address set) can only be paid on CRYPTO; every other rail rejects it.

On every rail other than CRYPTO and CHINA_OFFRAMP, when no quote_id is supplied the beneficiary's payment_details.currency must equal the account's currency, otherwise 400 VALIDATION_ERROR (there is no FX leg to reconcile the mismatch). A quote-driven payout is checked against the quote's target_currency instead.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Fields are optional at the schema level and required by rail. Omitting a required field, or sending a forbidden one, returns 400 VALIDATION_ERROR.
| Rail | Required | Not allowed | | --- | --- | --- | | ACH, FEDWIRE, SWIFT, SEPA, SEPA_INSTANT, FASTER_PAYMENTS, CHAPS | amount, description | quote_id | | CHINA_OFFRAMP | quote_id, purpose_code, file_ids | amount | | CRYPTO | amount | quote_id |

account_id

string

required

Funding account. On CRYPTO it must be the account of the asset being sent (its currency equals the beneficiary's payment_details.currency), otherwise 400 VALIDATION_ERROR.

beneficiary_id

string

required

customer_id

string

Optional when the account is already linked to a customer; required otherwise (400 CUSTOMER_REQUIRED). A customer not onboarded for this corridor returns 400 CUSTOMER_NOT_ONBOARDED.

rail

string

enum

required

Payment rail for a withdrawal. Must be enabled for your integration and the account currency; see WithdrawalCreationResource for per-rail field requirements.

amount

string

Positive string-encoded decimal. See the per-rail table above. On CRYPTO, ACH, FEDWIRE, and SWIFT this is the amount the beneficiary is sent; the payout fee is debited from the account in addition to it.

quote_id

string

See the per-rail table above. A customer-scoped quote (one that returns customer_id) must be spent from that customer's account (VALIDATION_ERROR otherwise).

description

string

length between 1 and 255

Payment reference shown on the transfer. See the per-rail table above.

purpose_code

string

enum

Reason for the payment. Required for the CHINA_OFFRAMP rail, and for SWIFT payouts to destination countries that mandate one (see PurposeCode).

Allowed:

file_ids

array of strings

Supporting documents (invoice/contract) previously uploaded via the customer upload endpoint. Required for the CHINA_OFFRAMP rail. Each document may back only one payout; reusing it is rejected.

file_ids

Headers

Idempotency-Key

string

required

Idempotency key required on all write requests. Replaying the same key with the same body returns the original response.

X-Api-Key

string

required

Your API key

X-Timestamp

string

required

Request timestamp (ISO 8601 UTC), included in the signature payload

X-Nonce

string

required

Unique request nonce (e.g. UUID)

X-Signature

string

required

HMAC-SHA256 hex digest of {METHOD}\n{path}\n{query}\n{X-Timestamp}\n{body}, signed with your API secret. Path excludes the query string; use an empty string for query/body when absent.

Responses

202Accepted

401Unauthorized

403Forbidden

409Conflict. Common codes: ACCOUNT_NOT_PROVISIONED, DUPLICATE_CLIENT_REFERENCE.

503The payment provider is temporarily unavailable. The request is safe to retry.