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

# How it works

> A remittance happens in three phases. A quote is only a price: it is not linked to a sender or a beneficiary. The sender and the beneficiary are informed in the withdrawal, so both must be ready before it: the sender registered, active and at LEVEL_1 or above, and the beneficiary approved. They can be registered before or after the quote.

**1. Sender**

*Done once per sender. Reused in every remittance.*

* **Onboarding** — MSB registers its customer: identification, address, documents.
* **Compliance** — LB Pay assigns a compliance level (`LEVEL_0` to `LEVEL_3`) and limits per window. `LEVEL_0` cannot send.

**2. Price and send**

*For each remittance.*

* **Quote** — MSB requests a price for a fixed USD or BRL amount. One price, short validity. Not linked to a sender.
* **Beneficiary** — Choose an existing beneficiary or register a new one with a Pix key. Before or after the quote; required for the withdrawal.
* **Withdrawal and funding** — MSB creates the withdrawal with the quote, sender, beneficiary, Pix key, purpose, relationship and funding mode. LB Pay validates, reserves credit or balance and creates the remittance.

**3. Execute and settle**

*Run by LB Pay.*

* **FX and funding** — FX contracted. `PREFUNDED`: USD debited from the MSB’s balance in the US. `CREDIT`: BRL advanced. `INVENTORY`: volume used from the lot, at the lot rate.
* **Pix and receipt** — LB Pay confirms the Pix key belongs to the beneficiary and credits the BRL. Receipt and notification issued.
* **Settlement** — For `CREDIT`, the MSB pays the settlement by the due date.

> [!NOTE]
>
> **USDC Inventory.** Instead of one quote per remittance, the MSB can contract FX volume in advance: request a quote with `usage = INVENTORY` and create an Inventory Lot with `POST /v1/inventories`. Each withdrawal then uses `funding.mode = INVENTORY`, the `inventoryId`, the BRL amount and `senderQuote`, with no `quoteId`. Rate and amounts come from the lot. See [USDC Inventory](https://developers.javalibridge.com/en/guides/inventory.md).

> [!NOTE]
>
> A quote can be requested without a sender or a beneficiary. A withdrawal can only be created with an eligible sender, an active, approved beneficiary and a valid Pix key. Because the sender is only checked at the withdrawal, check the sender’s status and limits before showing the price to your customer. If registering the beneficiary takes longer than the quote validity, request a new quote.

## Who does what, step by step

| # | Who | Action |
| - | - | - |
| 1 | MSB | Registers the sender |
| 2 | LB Pay | Assigns the compliance level and limits |
| 3 | MSB | Checks the sender’s status and limits, then requests a quote for a fixed USD or BRL amount |
| 4 | LB Pay | Returns the price: rate, FX spread and BRL amount |
| 5 | MSB | Chooses or registers the beneficiary with a Pix key |
| 6 | LB Pay | Screens the beneficiary and the Pix key |
| 7 | MSB | Creates the withdrawal with quote, sender, beneficiary, purpose, relationship and funding mode |
| 8 | LB Pay | Runs validations (quote, sender, beneficiary, limits), checks that the Pix key exists and reserves credit or USD balance |
| 9 | LB Pay | Creates the remittance, type `WITHDRAWAL` (`PROCESSING` or `ON_HOLD`) |
| 10 | LB Pay | Completes screening, contracts FX and confirms funding |
| 11 | LB Pay | Confirms the key holder matches the beneficiary and sends the Pix |
| 12 | Beneficiary | Receives BRL in their account |
| 13 | LB Pay | Notifies completion and issues the receipt |
| 14 | MSB | For credit: pays the settlement by the due date |

## With USDC Inventory

| # | Who | Action |
| - | - | - |
| 1 | MSB | Requests a quote with `usage = INVENTORY` for a fixed USD or BRL volume |
| 2 | LB Pay | Returns the price, the quote validity and the lot validity (`inventoryExpiresAt`) |
| 3 | MSB | Creates the lot with `POST /v1/inventories` and the `quoteId` |
| 4 | LB Pay | Creates the Inventory Lot (`ACTIVE`) and the USDC payment promise |
| 5 | MSB | Creates each withdrawal with `funding.mode = INVENTORY`, `inventoryId`, `destinationAmount` and `senderQuote` |
| 6 | LB Pay | Checks the lot (exists, within validity, enough balance), runs the usual validations and reserves the volume |
| 7 | LB Pay | Executes FX at the lot rate and sends the Pix |
| 8 | Beneficiary | Receives BRL in their account |
| 9 | LB Pay | Notifies by webhook; the lot balance moves from reserved to used |


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