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

> Pay out BRL over PIX to a Brazilian account, identified by a PIX key or by bank details. Covers who can receive BRL payouts, PIX destination registration, PIX key lookup, Autoramps, and errors.

BRL payouts go out over PIX. A PIX destination is registered through its own endpoints under `/api/addresses/pix`, not `/api/addresses/fiat`. See [Payouts](https://dev.enterprise.moonpay.com/offramp.md) for the overall flow.

## Who can receive BRL payouts

* **Individual customers only.** Business customers can't receive BRL payouts
* **No third-party flag.** PIX destinations have no `is_third_party` field, so every BRL payout counts as a first-party payout. In production, `abilities.fiat_payout.brl.pix_thirdparty` reads `Unavailable`. Sandbox reports it as `Active`, but sandbox doesn't support third-party PIX either

Read `abilities.fiat_payout.brl.pix` from `GET /api/customers/{customer_id}/abilities` to check a customer.

## Look up a PIX key first

`GET /api/pix-key-info` returns who a PIX key belongs to, without registering anything. Use it to show your customer the holder's name and bank before you register the destination.

```bash theme={null}
curl -X GET "https://api.sandbox.iron.xyz/api/pix-key-info?pix_key_type=PHONE&pix_key=%2B5511987654321" \
  -H "X-API-Key: <your-api-key>"
```

The response carries the holder's `name`, the `bank_name`, and the bank's 8-digit `ispb` code. `pix_key_type` is one of `CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `EVP`. An unknown key returns `404` with `"PIX key not found"`.

## Register the PIX destination

`POST /api/addresses/pix`

```bash PIX key theme={null}
curl -X POST "https://api.sandbox.iron.xyz/api/addresses/pix" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
    "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
    "label": "Primary PIX",
    "recipient": {
      "recipient": { "type": "Individual", "given_name": "João", "family_name": "Silva" },
      "account": { "type": "PHONE", "key": "+5511987654321" }
    }
  }'
```

```bash Bank details theme={null}
curl -X POST "https://api.sandbox.iron.xyz/api/addresses/pix" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
    "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
    "label": "Itaú checking",
    "recipient": {
      "recipient": { "type": "Individual", "given_name": "João", "family_name": "Silva" },
      "account": {
        "type": "BANK_DETAILS",
        "tax_id": "123.456.789-09",
        "bank_code": "341",
        "branch_code": "1234",
        "account_number": "5678901",
        "account_type": "CHECKING"
      }
    }
  }'
```

> [!NOTE]
>
> `POST /api/addresses/pix` 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).

`recipient.recipient` is the account holder's name: `Individual` with `given_name` and `family_name`, or `Business` with `name`, each 1-50 characters. `recipient.account` identifies the account by `type`:

| `type` | Fields | Format |
| - | - | - |
| `CPF` | `key` | 11 digits, with or without `XXX.XXX.XXX-XX` formatting |
| `CNPJ` | `key` | 14 digits, with or without `XX.XXX.XXX/XXXX-XX` formatting |
| `EMAIL` | `key` | Email address, up to 77 characters |
| `PHONE` | `key` | International format with a leading `+`, for example `+5511987654321` |
| `EVP` | `key` | The random key from the recipient's bank, as a lowercase UUID |
| `BANK_DETAILS` | `tax_id`, `bank_code`, `branch_code`, `account_number`, `account_type` | For recipients without a PIX key. `tax_id` is the holder's CPF or CNPJ. `bank_code` is a 3-digit COMPE or 8-digit ISPB code. `branch_code` is up to 4 digits, without the check digit. `account_number` includes its check digit, with no separator. `account_type` is `CHECKING`, `SAVINGS`, `SALARY`, or `TRANSACTION` |

The response is the PIX destination with its `id` and a `status`: `RegistrationPending`, then `Registered` once it's set up for payouts, or `RegistrationFailed`. Only a `Registered` destination works in an Autoramp.

## Create the payout Autoramp

Create a standing Autoramp or a quote-based Autoramp the same way as any payout, with BRL as the destination and the PIX destination's `id` as the recipient:

```json theme={null}
"destination_currency": { "type": "Fiat", "code": "BRL" },
"recipient_account": { "type": "Pix", "id": "<pix_address_id>" }
```

See [Payouts](https://dev.enterprise.moonpay.com/offramp.md#payout-with-an-exact-out-quote) for the full request. A PIX recipient with any other destination currency returns `400` with `"PIX payouts are only supported for BRL"`.

BRL Autoramps don't support:

* **Batch payouts.** `batch_payout: true` returns `400` with `"batch_payout is not supported for BRL destinations"`
* **Payment references.** The reference fields apply to bank accounts only

## Timing

See [Settlement Times by Payment Method](https://dev.enterprise.moonpay.com/transaction-status.md#settlement-times-by-payment-method).

## Fees and minimums

Fees come from the Autoramp's fee profile. See [Fees and Invoices](https://dev.enterprise.moonpay.com/fees-and-invoices.md). A payout under 1 BRL ends as `RejectedMinAmount`. See [Minimum Transaction Amount](https://dev.enterprise.moonpay.com/limits-and-minimum.md#minimum-transaction-amount).

## What can go wrong

| Response | Cause |
| - | - |
| `403` `{ "message": "PIX destinations are not yet available", "trace_id": "..." }` | BRL isn't enabled for your partner account. Contact the MoonPay Enterprise team |
| `400` `"destination currency is not supported as payout"` | BRL isn't enabled for your partner account, so the Autoramp can't pay out to a PIX destination |
| `404` `"PIX key not found"` | The key from `GET /api/pix-key-info` doesn't resolve to an account |
| `409` `"A PIX address with this account already exists for this customer"` | The destination is already registered. Reuse its ID |
| `400` `"recipient pix account not found"` | The `id` in `recipient_account` isn't a `Registered` PIX destination of this customer |
| `400` `"PIX payouts are only supported for BRL"` | The Autoramp's destination currency isn't BRL |

## Manage PIX destinations

| Action | Endpoint |
| - | - |
| List a customer's PIX destinations | `GET /api/addresses/pix/{customer_id}` |
| Get one PIX destination | `GET /api/addresses/pix/{customer_id}/{pix_address_id}` |
| Delete a PIX destination | `DELETE /api/addresses/pix/{customer_id}/{pix_address_id}` |