> ## Documentation Index
> Fetch the complete documentation index at: https://developers.javalibridge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a withdrawal

> A withdrawal sends money from a sender to a beneficiary in Brazil, and it is the only way to create a remittance in v1. It uses a quote for the price. In the withdrawal, the MSB informs who sends, who receives, why, and how the remittance is funded.

Endpoint: [`POST /v1/remittances/withdrawals`](https://developers.javalibridge.com/en/api-reference/create-withdrawal).

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

1. The request is not a duplicate and the external ID has not been used.
2. The quote exists, has not expired and has not been used.
3. The funding mode is enabled for your account.
4. 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.
5. The beneficiary is `ACTIVE` and the Pix key is `APPROVED`.
6. 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.
7. The amount is within the minimum and maximum per remittance and within the daily limit of your account.
8. The beneficiary has limit available in the 24-hour, 30-day and 180-day windows.
9. Credit limit (`CREDIT`) or USD balance in the US (`PREFUNDED`) is reserved for this remittance.

> [!NOTE]
>
> 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. |

> [!TIP]
>
> **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.