BRL virtual accounts

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.
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 or cancel 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:

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"
  }'

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.

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:

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

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"
  }'

200 OK

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

Timing

The transaction follows the usual transaction statuses.

Fees

The Autoramp’s fee profile decides the fees on each deposit. See 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 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.

Getting Started

Coverage

Onboarding & Compliance

Virtual Accounts & Global Payouts

Issuance

Wallets

Webhooks & Events

Billing & Settlement

Support

Who can get one

Requirements

Create a BRL virtual account

What your customer sees

BR codes with your own reference

Third-party deposits and pay by reference

Timing

Fees

What can go wrong

Sandbox

​Who can get one

​Requirements

​Create a BRL virtual account

​What your customer sees

​BR codes with your own reference

​Third-party deposits and pay by reference

​Timing

​Fees

​What can go wrong

​Sandbox

Who can get one

Requirements

Create a BRL virtual account

What your customer sees

BR codes with your own reference

Third-party deposits and pay by reference

Timing

Fees

What can go wrong

Sandbox