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

# BRL virtual accounts

> A PIX key and BR code for an individual customer. PIX payments in BRL convert to stablecoins. Covers who can get one, the one-Autoramp rule, KYC data, BR codes with your own reference, and what happens to deposits that can't be processed.

A BRL virtual account gives your customer a PIX key and a reusable BR code (PIX Copia e Cola). PIX payments to it convert to the Autoramp's stablecoin.

## Who can get one

| Customer | Eligible |
| - | - |
| Individual | Yes. One BRL Autoramp per customer |
| Business | No |

## Requirements

* The customer is `Active` and `fiat_deposit.brl.pix` reads `Active` in `GET /api/customers/{customer_id}/abilities`. See [Before you create a virtual account](https://dev.enterprise.moonpay.com/onramp.md#before-you-create-a-virtual-account).
* The customer is an individual. `brl.pix` can read `Active` for a business, but a business can't open a BRL Autoramp.
* The customer has no other BRL Autoramp that isn't `Cancelled` or `Rejected`. To move to a new stablecoin or wallet, [edit](https://dev.enterprise.moonpay.com/autoramp.md#edit-an-autoramp) or [cancel](https://dev.enterprise.moonpay.com/autoramp.md#cancel-an-autoramp) the existing Autoramp first.
* KYC data the PIX provider needs: date of birth and email address, plus a CPF for customers who live in Brazil. Customers who live elsewhere are identified by the number on their identity document.

## Create a BRL virtual account

In the dashboard, click **New Virtual Account** on the **Onramp** card under **Routes** and pick BRL. Through the API:

```bash theme={null}
curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
    "source_currencies": [{ "type": "Fiat", "code": "BRL" }],
    "destination_currency": { "type": "Crypto", "token": "USDC", "blockchain": "Solana" },
    "recipient_account": {
      "type": "Crypto",
      "chain": "Solana",
      "address": "3DkNYk8xJ9xGd1WsKZz8kG3n3QNB4f4pJ3m5mYxBV4Lm"
    },
    "customer_id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

> [!NOTE]
>
> `POST /api/autoramps` requires an `Idempotency-Key` header. A missing key returns `400`. Only successful responses are cached, so a retry after an error runs again. See [Idempotency](https://dev.enterprise.moonpay.com/idempotency.md).

The Autoramp stays `Authorized` until the PIX provider approves the customer's KYC, then moves to `Approved`. BRL Autoramps have no provisioning cutoff: they don't move to `Rejected` after 72 hours like other Autoramps.

## What your customer sees

An `Approved` BRL Autoramp returns one `Pix` entry in `deposit_rails`:

```json theme={null}
"deposit_rails": [
  {
    "type": "Pix",
    "br_code": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000...6304ABCD",
    "pix_key": "123e4567-e12b-12d1-a456-426655440000",
    "amount": null,
    "expires_at": null,
    "instruction": "Open your bank app and send Pix to the key, or use Pix Copia e Cola with the BR code."
  }
]
```

| Field | Description |
| - | - |
| `br_code` | The reusable PIX Copia e Cola payload. The payer pastes it into their bank app, or you render it as a QR code. Always present |
| `pix_key` | The PIX key, for payers who prefer to enter a key |
| `amount` | `null` on a BRL Autoramp: the payer chooses the amount |
| `expires_at` | `null`: the code doesn't expire |
| `instruction` | Payer guidance you can show as is. Always present |

## BR codes with your own reference

To tag a payment, generate a BR code that carries your reference, and optionally a fixed amount, with `POST /api/autoramps/{autoramp_id}/br-code`. The Autoramp must be `Approved`.

```bash theme={null}
curl -X POST "https://api.sandbox.iron.xyz/api/autoramps/{autoramp_id}/br-code" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
    "reference": "INV20260115",
    "amount": "250.00"
  }'
```

```json 200 OK theme={null}
{
  "br_code": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000...6304EF01"
}
```

The BR codes in these examples are shortened.

| Field | Required | Description |
| - | - | - |
| `reference` | Yes | 1 to 19 letters and digits. Returned on the resulting transaction as `inbound_payment_reference` |
| `amount` | No | A fixed amount in BRL, at least `0.01`, with at most 2 decimal places. Leave it out to let the payer choose |

Calling it again with the same parameters returns the same code. An Autoramp that isn't `Approved` returns `400` with `"Autoramp is not approved"`.

## Third-party deposits and pay by reference

PIX accounts accept payments from third parties, but you can't create a BRL Autoramp flagged as third-party, and BRL Autoramps don't support [pay by reference](https://dev.enterprise.moonpay.com/autoramp.md#pay-by-reference). In production, `fiat_deposit.brl.pix_thirdparty` reads `Unavailable`. Sandbox reports it as `Active`, but sandbox doesn't support third-party PIX either. To tell payments apart, use a [BR code with your own reference](#br-codes-with-your-own-reference).

## Timing

The transaction follows the usual [transaction statuses](https://dev.enterprise.moonpay.com/transaction-status.md).

## Fees

The Autoramp's fee profile decides the fees on each deposit. See [Fees on a deposit](https://dev.enterprise.moonpay.com/onramp.md#fees-on-a-deposit).

## What can go wrong

| What you see | Cause and fix |
| - | - |
| `400` `"Pix deposits are only supported for individual customers"` | The customer is a business. BRL accounts are for individuals only |
| `400` `"Customer already has a Pix onramp"` | The customer already has a live BRL Autoramp. Edit or cancel that one first |
| `400` `"source currency is not supported as pay-in"` | BRL isn't enabled for your partner account. `fiat_deposit.brl.pix` reads `Unavailable` for every customer in that case. Contact the MoonPay Enterprise team |
| Autoramp stays `Authorized` | The PIX provider hasn't approved the customer's KYC yet. Check that the KYC data above is complete |
| `400` `"amount must be at least 0.01 with at most 2 decimal places"` | The BR code `amount` is below 0.01 or has more than 2 decimals |
| `400` `"Autoramp has no deposit account yet"` | The Autoramp isn't provisioned yet. Wait for `Approved` before you request a BR code |
| A payment didn't convert | A PIX deposit that can't be processed, for example because the customer is suspended, isn't returned automatically. It stays with the PIX provider. Contact [support](https://dev.enterprise.moonpay.com/support.md) with the amount, date, and payer to recover it |

## Sandbox

Approve the Autoramp with `PUT /api/sandbox/autoramp/{id}` and simulate a deposit with `POST /api/sandbox/transaction`. In sandbox, `POST /api/autoramps/{autoramp_id}/br-code` returns a placeholder (`sandbox-br-code-` plus your reference), not a scannable code. See [Test the full flow in Sandbox](https://dev.enterprise.moonpay.com/onramp.md#test-the-full-flow-in-sandbox).