Skip to main content
POST
Create a withdrawal

Authorizations

Authorization
string
header
required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Idempotency-Key
string
required

Key that makes the request safe to retry. Any non-blank string of up to 255 characters. See Idempotency.

Maximum string length: 255
Example:

"00000000-0000-4000-8000-000000000001"

X-Trace-Version
string

API version. Omit to use the default version.

Example:

"1"

Body

application/json

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.

accountId
string<uuid>
required

Account that funds the withdrawal. The referenced quote belongs to your customer, so any of your accounts can consume it.

Example:

"a1b2c3d4-5e6f-7890-abcd-ef1234567890"

quoteId
string<uuid>
required

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.

Example:

"d4e5f6a7-b8c9-0123-defa-2345678901bc"

beneficiary
Reference · object
required

Beneficiary for the withdrawal. Discriminated by mode.

  • REFERENCE — points at a saved beneficiary by id.
externalId
string | null

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.

Required string length: 1 - 255
Example:

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

id
string<uuid>
required
read-only
externalId
string | null
required

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.

Required string length: 1 - 255
Example:

"order-2026-0043"

customer
object
required

Reference to the customer that owns the operation.

account
object
required

Reference to a customer account, including the registered owner name.

sourceAmount
object
required

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.

targetAmount
object
required

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.

intent
Withdrawal · object
required

Operation intent. Discriminated by type.

quote
object | null
required

Consumed quote. null for deposits created without a prior quote; present for all other operations.

refund
object | null
required

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.

fees
object[]
required
transactions
(PIX · object | Crypto · object | TED · object | Boleto · object | Internal debit · object | Internal credit · object)[]
required

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.

tags
object[]
required

System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.

Example:
requirements
object
required

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.

Example:
currentState
object
required

The operation's current state. Carries a status, optional reason, and the time the state was entered.

createdAt
string<date-time>
required
read-only
updatedAt
string<date-time>
required
read-only