Brazil

The necessary information for Brazil is presented below in order to carry out a correct payout.

Mandatory parameters

Field

Description

country

String (Required - Lenght: 3 digits)

ISO 3166-1-alpha-3. In the case of Brazil: BRA

amount

Integer (Required max-lenght : 10)

The amount of the transaction.The 2 last digits will be consider as decimal. Ex: 100000 equals "one thousand"

currency

String (Required - Lenght: 3 digits)

The currency of the payroll. ISO-4217. In the case of BRA: BRL You can see the explication on Currencies

orderId

String (Required - Lenght: 20 digits)

Merchant transaction code (Purchase Order)

description

String (Optional - Lenght: 50 digits)

For customer use

beneficiary.name

String (Required)

Name of the Beneficiary

beneficiary.lastName

String (Required)

Last name of the Beneficiary

beneficiary.email

String (Optional - max lenght: 50 digits)

Beneficiary's email

beneficiary.document.type

Integer (Required)

Type of Account of the beneficiary to pay. You must enter the numeric code as indicated

beneficiary.document.number

String (Required)

Contains the beneficiary's document number.

destination.bankAccount.bankCode

String (Required for Bank Transfer)

Code of the receiving bank or financial institution. For Brazil you must send de ISPB (Identificador de Sistema de Pagamentos Brasileiro), a unique identifier used by financial institutions within the Brazilian payment system

destination.bankAccount.accountType

Integer (Required) Type of Account of the beneficiary to pay.

destination.bankAccount.accountNumber

String (Required)

Beneficiary's account number.

destination.paymentMethod

String (Required)

Payment method for processing the payout. For Brazil could be "PIX" o "Bank Transfer"

destination.accountAgency

String (Required for Bank Transfer)

Identifies the specific bank branch or Agency. Some banks require just digits, while others include a check digit for verification. Regex: ^(([0-9]{1,6})|([0-9]{1,5}-[0-9]))$

Examples:

5
123
999999
12345-6

subMerchantInfo.code

String (Required only for PSP) Submerchant Identifier

subMerchantInfo.name

String (Required only for PSP) Submerchant Name

subMerchantInfo.url

String (Required only for PSP) Submerchant URL

New Feature

Email Notification to the Beneficiary

It is now possible to automatically send emails to the beneficiary with the outcome of the Payout (success or rejected).

Requirements:

Request the activation of "Email notifications to the user" through your account manager.
Include the beneficiary.email parameter in each transaction. If this field is missing, the email will not be sent.

IMPORTANT

For payment method "PIX" the next fields are OPTIONAL:

destination.bankAccount.bankCode
destination.accountAgency
When providing a "phone" (Account Type: 3) as a key, it MUST be provided with the country IDD (International Direct Dialing) at the beginning of the number. For Brazil the field should start with “+55”.

For payment method "Bank Transfer" the next fields are MANDATORY:

destination.bankAccount.bankCode
destination.accountAgency
destination.bankAccount.accountNumber
When providing an Account Type, it must provide Checking Account, Savings Account or Payment Account

IMPORTANT

For Brazil the maximum amount allowed is 50,000 BRL
The minimum amount is 0.01 BRL
Reversed payouts can be notified up to 90 days after the original payment was made. SOPORTAR 2DA NOTIFICACIÓN

Request Example

Pix payout using "Phone" (Account Type = 3)

{
  "country": "BRA",
  "amount": 5000000,
  "currency": "BRL",
  "orderId": "BJB",
  "beneficiary": {
    "name": "Iam",
    "lastName": "Torres",
    "email": "[email protected]",
    "document": {
      "type": 1,
      "number": "31192071280"
    }
  },
  "destination": {
    "paymentMethod": "1",
    "accountAgency": "",
    "bankAccount": {
      "bankCode": "",
      "accountType": 4,
      "accountNumber": "+5511987654321"
    }
  }
}

Bank Transfer payout using "Payment Account" (Account Type = 7)

{
  "country": "BRA",
  "amount": 50000,
  "currency": "BRL",
  "orderId": "BJB_{{randomUUID}}",
  "beneficiary": {
    "name": "Iam",
    "lastName": "Torres",
    "email": "[email protected]",
    "document": {
      "type": 1,
      "number": "31192071280"
    }
  },
  "destination": {
    "paymentMethod": "2",
    "accountAgency": "123456",
    "bankAccount": {
      "bankCode": "90400888",
      "accountType": 7,
      "accountNumber": "12345671-1"
    }
  }
}

Time Outs

In the case of receiving a Time Out as a response from this API we recommend resending the payout again after 30 seconds using the same orderId.

This way we will check if the payout was processed and avoid double payments.

Document Validations

Parameter

Document Type

Regex

Examples

CPF

^[0-9]{11}$

12345678901

CNPJ

^[0-9]{14}$

12345678901234

Payment Method

Parameter

Type

PIX

Bank Transfer

Account Type

Parameter

Account Type

Regex

Examples

Payment Method available

CPF

^[0-9]{11}$

12345678901

PIX

CNPJ

^[0-9]{14}$

12345678901234

PIX

Phone

^+[1-9][0-9]\d{1,14}$

+5515512345678

PIX

[email protected]

PIX

UUID

[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

123e4567-e89b-12d3-a456-426655440000

PIX

Checking Account

^(([0-9]{2,20})|([0-9]{2,19}-[0-9]))$

12345678901234567890
9876543219876543219-4

BANK TRANSFER

Payment Account

^(([0-9]{2,20})|([0-9]{2,19}-[0-9]))$

12345678901234567890

9876543219876543219-4

BANK TRANSFER

Savings Account

^(([0-9]{2,20})|([0-9]{2,19}-[0-9]))$

12345678901234567890

9876543219876543219-4

BANK TRANSFER

Bank List

The Central Bank of Brazil has over 800 participating entities for instant bank transfers. Below is the updated list of entities according to the BCB (Please edit to the current date before inquiry this URL):

https://www.bcb.gov.br/content/estabilidadefinanceira/participantes_pix_pdf/lista-participantes-instituicoes-em-adesao-pix-20250624.pdf

We present the main entities in the list:

Bank Name

BankCode (ISPB)

Itaú Unibanco

60701190

Bradesco

60746948

Banco do Brasil

00000000

Caixa Econômica Federal

00360305

Santander

90400888

Sicoob

02038232

BTG Pactual

30306294

Banco Safra

58160789

Banco Votorantim (BV)

59588111

Banrisul

92702067

Citibank

33042953

Banco do Nordeste

07237373

Banco Original

92894922

Pagbank (PagSeguro)

08561701

Nubank

18236120

Mercado Pago

10573521

AME Digital

32778350

C6 Bank

31872495

Banco Inter

00416968

Last updated 6 days ago