How to Create a BRL Transfer

BRL transfers send funds to a Brazilian bank account. Unlike EUR and USD transfers, bank accounts in LATAM are not associated with beneficiaries — they are created automatically at the moment the transfer is submitted.

There are three ways to create a BRL transfer:

• Option A — New transfer with full bank data (creates the bank account inline)
• Option B — New transfer with a PIX key (creates the bank account inline)
• Option C — Reuse a previously created bank account via bankAccountId

PDF attachments are optional for BRL transfers. If included: maximum 10 files, maximum 1 MB per file, PDF format only.

---

Option A — Full Bank Data

Pass complete bank account data directly in the transfer body. A new bank account is created automatically and linked to the transfer.

Required fields for this option:

Field	Description
currency	BRL
amount	Amount in BRL
bankCountry	Country code (BR)
accountNumber	Bank account number
bankAccountName	Account holder name
bankName	Bank name
bankCode	Bank agency number

Request

curl -X POST "/api/v1/transfer" \
  -H "Authorization: Bearer <token>" \
  -F "currency=BRL" \
  -F "amount=5000.00" \
  -F "bankCountry=BR" \
  -F "accountNumber=12345-6" \
  -F "bankAccountName=João da Silva" \
  -F "bankName=Itaú Unibanco" \
  -F "bankCode=0341"

---

Option B — PIX Key

Use a PIX key as the accountNumber. In this case, bankName and bankCode are not required.

Required fields for this option:

Field	Description
currency	BRL
amount	Amount in BRL
bankCountry	Country code (BR)
accountNumber	PIX key (CPF, CNPJ, phone, email, or random key)
bankAccountName	Account holder name

Request

curl -X POST "/api/v1/transfer" \
  -H "Authorization: Bearer <token>" \
  -F "currency=BRL" \
  -F "amount=5000.00" \
  -F "bankCountry=BR" \
  -F "accountNumber=joao.silva@email.com" \
  -F "bankAccountName=João da Silva"

---

Option C — Existing Bank Account

If a bank account was previously created through a prior transfer, it can be reused by passing its id as bankAccountId. No bank account fields are needed.

List existing Brazilian bank accounts

curl -X GET "/api/v1/bank-account?bankCountry=BR" \
  -H "Authorization: Bearer <token>"

This returns a paginated list of bank accounts linked to the authenticated user. Use the id of the desired account.

Request

curl -X POST "/api/v1/transfer" \
  -H "Authorization: Bearer <token>" \
  -F "bankAccountId=d6c6c357-343f-4106-8f7d-b678c60ff10a" \
  -F "currency=BRL" \
  -F "amount=5000.00" \

---

Response (201) — All options

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transferNumber": "002095696342671878",
  "status": "pending",
  "currency": "BRL",
  "amount": "5000.00",
  "amountInUSD": "950.57",
  "quote": "5.26",
  "pdfDocuments": [],
  "bankAccount": {
    "id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
    "name": "João da Silva",
    "bankCountry": "BR",
    "accountNumber": "12345-6",
    "bankName": "Itaú Unibanco",
    "bankCode": "0341"
  },
  "createdAt": "2026-05-14T12:05:00.000Z",
  "updatedAt": "2026-05-14T12:05:00.000Z"
}

---

Balance Impact

Event	Effect on Balance
Transfer created	amountInUSD is immediately deducted from the user's available balance
Transfer rejected	Amount is automatically restored to the user's balance