Create a withdrawal
Creates a new withdrawal to a saved beneficiary.
Authorizations
JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.
Headers
Key that makes the request safe to retry. Any non-blank string of up to 255 characters. See Idempotency.
255"00000000-0000-4000-8000-000000000001"
API version. Omit to use the default version.
"1"
Body
Every withdrawal references a quote previously obtained from POST /v1/quotes. The quote determines sourceAmount and targetAmount and locks the FX rate (or the 1:1 spot for same-asset). A quote can be consumed by at most one operation.
Account that funds the withdrawal. Must match the account on the referenced quote.
"a1b2c3d4-5e6f-7890-abcd-ef1234567890"
ID of a quote returned by POST /v1/quotes. Must belong to the same customer, must not have expired, and must not have been consumed by another operation.
"d4e5f6a7-b8c9-0123-defa-2345678901bc"
Beneficiary for the withdrawal. Discriminated by mode.
REFERENCE— points at a saved beneficiary byid.
Your own identifier for the operation. Stored as given and returned on every read and every webhook. Free-form: it is not deduplicated, and the same value may appear on more than one operation. null when none was sent, and on a deposit credited from an incoming payment nobody requested.
1 - 255"order-2026-0043"
Response
Withdrawal accepted. The operation is in REQUESTED status.
A created operation. Withdrawals, swaps, deposits, and transfers share this shape; intent.type identifies which.
Your own identifier for the operation. Stored as given and returned on every read and every webhook. Free-form: it is not deduplicated, and the same value may appear on more than one operation. null when none was sent, and on a deposit credited from an incoming payment nobody requested.
1 - 255"order-2026-0043"
Reference to the customer that owns the operation.
Reference to a customer account, including the registered owner name.
Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.
Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.
Operation intent. Discriminated by type.
- Withdrawal
- Swap
- Deposit
- Transfer
Consumed quote. null for deposits created without a prior quote; present for all other operations.
The refund you asked for on this deposit. null on every operation nobody asked back, and on a return the payer's bank issued on its own.
Rail-level transactions for the operation. Only confirmed transactions are included; pending or failed rail movements are omitted.
A rail-level transaction associated with the operation. Discriminated by type, which names the rail that moved the money — INTERNAL_DEBIT and INTERNAL_CREDIT are the two legs of a movement that stays inside the platform and touches no external rail.
- PIX
- Crypto
- TED
- Boleto
- Internal debit
- Internal credit
What compliance is waiting on for this operation, read live at request time. All four groups are empty for an operation that never went through a compliance review. An operation in ACTION_REQUIRED is waiting on whatever is in currentlyDue and errors.
The operation's current state. Carries a status, optional reason, and the time the state was entered.
System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.