Creating a withdrawal

Endpoint: POST /v1/remittances/withdrawals.

Information required

Item	Description
Quote	An `AVAILABLE` quote that has not expired. Defines the amounts and the rate.
Sender	A registered sender, active, at `LEVEL_1` or above and with limit available.
External ID	Your own unique reference for the remittance. It cannot repeat.
Beneficiary	A registered beneficiary, `ACTIVE`, with an `APPROVED` Pix key.
Payment instruction	The Pix key to be paid. Optional when the beneficiary has exactly one `APPROVED` key.
Purpose	`FAMILY_MAINTENANCE`, `GIFT`, `PERSONAL_SAVINGS`, `EDUCATION`, `MEDICAL`, `SERVICES_PAYMENT`, `GOODS_PAYMENT`, `SALARY`, `OTHER`.
Purpose description	Required when purpose is `OTHER`. Up to 140 characters.
Sender relationship	Relationship of the sender with the beneficiary: `SELF`, `FAMILY`, `FRIEND`, `EMPLOYER`, `EMPLOYEE`, `BUSINESS_PARTNER`, `OTHER`.
Funding mode	`PREFUNDED` or `CREDIT`.

Validations before FX

These checks run immediately, before any funding or FX is committed. If one fails, the withdrawal is rejected and no FX is contracted.

The request is not a duplicate and the external ID has not been used.
The quote exists, has not expired and has not been used.
The funding mode is enabled for your account.
The sender exists, is active, has a level that allows sending (LEVEL_1 or above) and has limit available in the 24-hour, 30-day and 180-day windows.
The beneficiary is ACTIVE and the Pix key is APPROVED.
Pix key check: the key exists. This prevents FX for a key that does not exist. Who holds the key is confirmed later, just before the Pix.
The amount is within the minimum and maximum per remittance and within the daily limit of your account.
The beneficiary has limit available in the 24-hour, 30-day and 180-day windows.
Credit limit (CREDIT) or USD balance in the US (PREFUNDED) is reserved for this remittance.

Sanctions screening and AML rules may place a remittance ON_HOLD for manual review instead of rejecting it, at creation or during screening. FX is only contracted after screening is complete.

Common rejection reasons

Code	What it means and what to do
`QUOTE_EXPIRED`	The quote expired. Request a new quote and create the withdrawal again.
`QUOTE_ALREADY_USED`	The quote was already used by another withdrawal. Check the remittance it created (the quote shows its remittance ID), or request a new quote.
`DUPLICATE_EXTERNAL_ID`	The external ID was already used. Use a new one, or look up the existing remittance.
`SENDER_NOT_ELIGIBLE`	The sender does not exist, is not active or is at `LEVEL_0`. Complete the sender’s data. Check the sender before quoting to avoid it.
`SENDER_LIMIT_EXCEEDED`	The sender reached a window limit. Wait for the window or upgrade the compliance level.
`BENEFICIARY_NOT_ELIGIBLE`	The beneficiary is not `ACTIVE`.
`RELATIONSHIP_MISMATCH`	The relationship informed does not match the beneficiary type (`SELF_OWNED` requires `SELF`).
`BENEFICIARY_LIMIT_EXCEEDED`	The beneficiary reached a window limit. Wait for the window.
`PAYMENT_INSTRUCTION_INVALID`	The instruction cannot be used. Choose another active instruction for the beneficiary.
`PIX_KEY_NOT_FOUND`	The Pix key does not exist. Confirm the key with the beneficiary.
`CREDIT_LIMIT_EXCEEDED`	The credit limit is not enough. Use `PREFUNDED` or wait for a settlement.
`INSUFFICIENT_PREFUNDED_BALANCE`	The USD balance in the US is not enough. Transfer USD following the funding instructions, or use `CREDIT`.
`FUNDING_MODE_NOT_ENABLED`	This funding mode is not enabled for your account.
`AMOUNT_BELOW_MINIMUM` / `AMOUNT_ABOVE_LIMIT`	The amount is outside the limits per remittance set for your account. Adjust it.
`ACCOUNT_DAILY_LIMIT_EXCEEDED`	Your account reached the daily limit. Wait for the next day.
`SERVICE_UNAVAILABLE`	Temporary, including maintenance. Try again later.

What you do

Send quote, sender, beneficiary, Pix key, purpose, relationship and funding mode.
Use a new external ID for every remittance.
When a request is rejected, read the code and follow the action in the table.

Get started

Remittances

Records and balances

Operations

Information required

Validations before FX

Common rejection reasons

​Information required

​Validations before FX

​Common rejection reasons

Information required

Validations before FX

Common rejection reasons