Initialize a payout
Step 2 of 3: attaches a beneficiary to a quote and returns the final fees and total_amount. The beneficiary must meet the country’s requirements (GET /api/payouts/supported-countries/). For an onchain quote, address and deposit_amount say where and how much to send.
Authorizations
Your workspace client id.
All calls must include four headers:
X-Auth-Client— your workspace client idX-Auth-Timestamp— Unix secondsX-Auth-Nonce— 16-byte random hexX-Auth-Signature— hex(HMAC-SHA256({client_id}:{timestamp}:{nonce}:{raw_body}, client_secret))
The playground computes the timestamp, nonce and signature for you.
Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration.
Path Parameters
The quote_id returned when the quote was created
Body
Beneficiary details. The fields depend on the country and destination type; see GET /api/payouts/supported-countries/{country}. USD payouts need destination_type (ach, wire or swift). A sender object may be supplied. On a personal (individual) account it is ignored on every rail; the sender is the owner's verified identity, and a rail whose sender needs details that identity does not hold is refused (422, error_code SENDER_DETAILS_UNAVAILABLE).
HTTPS URL that receives updates for this payout.
Make the payout on behalf of this customer. Needs the customers and customer_payouts features. A value that is not a UUID is ignored and the payout is made without a customer; a UUID with no customer is refused (400 unknown_customer).
Key of an uploaded invoice (SWIFT); must start with tmp/{your company id}/
512A JSON object encoded as a string; ignored if it does not parse
Reason for the payment.
255Your unique reference for this payout.
255Response
OK
Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead.
true on success
When the response was written.
The payload; its shape is given per operation. Omitted when there is none.
Human-readable summary; omitted when empty.
List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set.
Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support.