Skip to main content

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:

RailUse it when you haveBank details needed
BR_PIXA PIX key (CPF, CNPJ, email, phone, or random key)No
BR_TEDA bank account numberYes: 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:

FieldDescription
currencyBRL
amountAmount in BRL
destination.railBR_PIX
destination.countryBR
destination.accountIdentifierValuePIX key: CPF, CNPJ, email, phone number, or random key
destination.beneficiary.nameAccount holder name
destination.beneficiary.taxIdAccount holder CPF or CNPJ
destination.beneficiary.countryBR

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:

FieldDescription
currencyBRL
amountAmount in BRL
destination.railBR_TED
destination.countryBR
destination.accountIdentifierValueBank account number
destination.institution.schemeBR_ISPB
destination.institution.identifierBank ISPB code (8 digits)
destination.institution.nameBank name
destination.institution.branchCodeBank branch (agency) number
destination.beneficiary.nameAccount holder name
destination.beneficiary.taxIdAccount holder CPF or CNPJ
destination.beneficiary.countryBR

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&currency=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 id or 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​

EventEffect on Balance
Transfer createdamountInUSD is immediately deducted from the user's available balance
Transfer rejectedAmount 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.