BRL payouts

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

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

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

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

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.

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:

"destination_currency": { "type": "Fiat", "code": "BRL" },
"recipient_account": { "type": "Pix", "id": "<pix_address_id>" }

See Payouts 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.

Fees and minimums

Fees come from the Autoramp’s fee profile. See Fees and Invoices. A payout under 1 BRL ends as RejectedMinAmount. See 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}`

Getting Started

Coverage

Onboarding & Compliance

Virtual Accounts & Global Payouts

Issuance

Wallets

Webhooks & Events

Billing & Settlement

Support

Who can receive BRL payouts

Look up a PIX key first

Register the PIX destination

Create the payout Autoramp

Timing

Fees and minimums

What can go wrong

Manage PIX destinations

​Who can receive BRL payouts

​Look up a PIX key first

​Register the PIX destination

​Create the payout Autoramp

​Timing

​Fees and minimums

​What can go wrong

​Manage PIX destinations

Who can receive BRL payouts

Look up a PIX key first

Register the PIX destination

Create the payout Autoramp

Timing

Fees and minimums

What can go wrong

Manage PIX destinations