How to Create a BRL Bank Transfer
BRL bank transfers send funds to a Brazilian bank account. The destination is a payout destination: the bank details (or PIX key) and the beneficiary that owns them. You don't need to create anything beforehand: the destination is created automatically when you submit the transfer, or you can reuse one you already have.
There are two payment rails for Brazil, and the one you pick decides which fields you need:
| Rail | Use it when you have | Bank details needed |
|---|---|---|
BR_PIX | A PIX key (CPF, CNPJ, email, phone, or random key) | No |
BR_TED | A bank account number | Yes: bank (ISPB), bank name and branch |
In both cases the beneficiary's name and tax ID (CPF or CNPJ) are required.
You can create a BRL transfer in three ways:
- Option A — New transfer using a PIX key
- Option B — New transfer with full bank data (TED)
- Option C — Reuse a previously created payout destination with its
id
PDF attachments are optional for BRL transfers. If included: maximum 10 files, maximum 1 MB per file, PDF format only.
Read the Bank Transfers Overview first for authentication, the request format and the transfer lifecycle.
Endpoint
POST /payout/transfer
API Reference: Create a bank transfer
The request is multipart/form-data. The destination field is sent as a JSON-encoded string.
Option A — PIX Key
Use rail BR_PIX. Pass the PIX key as accountIdentifierValue. The API detects the key type automatically. No bank details are required.
Required fields for this option:
| Field | Description |
|---|---|
currency | BRL |
amount | Amount in BRL |
destination.rail | BR_PIX |
destination.country | BR |
destination.accountIdentifierValue | PIX key: CPF, CNPJ, email, phone number, or random key |
destination.beneficiary.name | Account holder name |
destination.beneficiary.taxId | Account holder CPF or CNPJ |
destination.beneficiary.country | BR |
destination.label is optional and lets you find the destination later, for example "João - PIX email". The beneficiary type is optional: it is inferred from the tax ID.
Request
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=BRL" \
-F "amount=5000.00" \
-F 'destination={"rail":"BR_PIX","country":"BR","accountIdentifierValue":"joao.silva@email.com","label":"João - PIX email","beneficiary":{"name":"João da Silva","taxId":"11144477735","country":"BR"}}'
Option B — TED with Full Bank Data
Use rail BR_TED. Pass the bank account number as accountIdentifierValue and describe the bank in institution. The bank is identified by its ISPB code, so institution.scheme must be BR_ISPB.
Required fields for this option:
| Field | Description |
|---|---|
currency | BRL |
amount | Amount in BRL |
destination.rail | BR_TED |
destination.country | BR |
destination.accountIdentifierValue | Bank account number |
destination.institution.scheme | BR_ISPB |
destination.institution.identifier | Bank ISPB code (8 digits) |
destination.institution.name | Bank name |
destination.institution.branchCode | Bank branch (agency) number |
destination.beneficiary.name | Account holder name |
destination.beneficiary.taxId | Account holder CPF or CNPJ |
destination.beneficiary.country | BR |
The ISPB must belong to a registered Brazilian bank, otherwise the request is rejected.
Request
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=BRL" \
-F "amount=5000.00" \
-F 'destination={"rail":"BR_TED","country":"BR","accountIdentifierValue":"12345-6","institution":{"scheme":"BR_ISPB","identifier":"60701190","name":"Itaú Unibanco","branchCode":"0001"},"beneficiary":{"name":"João da Silva","taxId":"11144477735","country":"BR"}}'
Option C — Existing Payout Destination
If a payout destination was created before, by a previous transfer or directly through the destinations API, reuse it by passing its id. No other destination fields are needed.
Find an existing Brazilian destination
curl -X GET "/api/v1/payout-destination?country=BR¤cy=BRL" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>"
This returns a paginated list of the active payout destinations of the authenticated user. Use the optional search parameter to look for a label or bank name, and use the id of the destination you want.
Request
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=BRL" \
-F "amount=5000.00" \
-F 'destination={"id":"d6c6c357-343f-4106-8f7d-b678c60ff10a"}'
Send either
idor the destination fields, never both.
Attaching PDF files (optional)
Add one -F "files=@..." part per file to any of the requests above.
-F "files=@invoice.pdf" \
-F "files=@transfer_order.pdf"
Response (201) — All options
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "transfer",
"payoutNumber": "002095696342671878",
"status": "pending",
"currency": "BRL",
"amount": "5000.00",
"amountInUSD": "950.57",
"quote": "5.26",
"pdfDocuments": [],
"destination": {
"id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
"label": "João - PIX email",
"rail": "BR_PIX",
"country": "BR",
"currency": "BRL",
"accountIdentifierScheme": "BR_PIX_EMAIL",
"accountIdentifierValue": "joao.silva@email.com",
"beneficiary": {
"name": "João da Silva",
"taxId": {
"scheme": "BR_CPF",
"value": "11144477735"
}
}
},
"createdAt": "2026-05-14T12:05:00.000Z",
"updatedAt": "2026-05-14T12:05:00.000Z"
}
destination is a snapshot of the destination taken when the transfer was created. Later edits to the destination don't change it.
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 |
amountInUSD and quote are calculated by the API from the current BRL exchange rate when the transfer is created.
If the transfer is rejected
When the payment provider rejects a transfer, the payout moves to rejected and the reason is returned in metadata.payoutProvider.reason, for example when the CPF or CNPJ sent does not match the one registered for the account. Double-check the beneficiary tax ID before submitting.