# Brazil

> Create a Payout for Brazil using our API and Dashboard

export const pix = PAYOUT_PAYMENT_METHODS.find((method) => method.id === "pix");

export const mercadoPago = PAYOUT_PAYMENT_METHODS.find(
  (method) => method.id === "mercado-pago",
);

export const ted = PAYOUT_PAYMENT_METHODS.find((method) => method.id === "ted");

# 🇧🇷 Brazil

Learn everything you need to know about making payouts in Brazil.

## Payment Methods

Checkout our SLAs for each payment method:

## Instructions

To create a payout using EBANX Direct API, follow the steps below.

  ### Define request parameters

    Provide the required parameters listed below to create a payout.

    
      | Field                | Description                                                                                                                      |
      | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
      | `integration_key`    | Your EBANX integration key.                                                                                                      |
      | `external_reference` | The unique payout ID provided by you.                                                                                            |
      | `country`            | The two-letter country code for the customer country. In this case, we'll show the method to br (Brazil)                         |
      | `amount`             | The amount in the specified currency (currency_code).                                                                            |
      | `currency_code`      | Three-letter code of the payout currency. In this case, we'll use BRL (Brazil)                                                   |
      | `payee`              | A JSON object containing the details of the payee of your request.                                                               |
      | `target`             | The payment method that will be used. Can be left empty and the payout target will be assumed as Bank Transfer. More info below. |
    

    
    **Document Types Allowed**

    These document types are used to identify payees or shareholders.

    
      | Document type | Description                                      |
      | ------------- | ------------------------------------------------ |
      | CPF           | An 11-digit Tax ID used to identify individuals. |
      | CNPJ          | A 14-digit Tax ID used to identify companies.    |

  ### Send payout request to EBANX

    To create a new Payout, you will use the [**/ws/payout/create**](/api-reference?api=payout&page=post--ws-payout-create) endpoint.

    The following example is a payout create request to the payee's bank account sending bank data with bank details:

    ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "external_reference": "{{unique_external_reference}}",
    "country": "br",
    "amount": 10,
    "currency_code": "USD",
    "payee": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+554112345678",
        "document": "{{tax_id}}",
        "document_type": "CPF",
        "bank_info": {
            "bank_name": "104  Caixa Econômica",
            "bank_branch": "{{bank_branch}}",
            "bank_account": "{{bank_account}}",
            "account_type": "C",
            "bank_details": "001"
        },
        "address": {
            "zipcode": "80320070",
            "state": "PR",
            "city": "Curitiba",
            "street_address": "Fake Street",
            "street_complement": "123"
        }
    }
}'
```

    When onboarding payees in Brazil, you can trigger a **self-onboarding flow** by submitting partial data. This sends an automatic email to the payee to finalize their registration.

    When `bank_details` is not provided (or is null), the **Operation** value defaults to the following mapping:

    
      | Document type | Account Type  | Operation |
      | ------------- | ------------- | --------- |
      | CPF           | S (Savings)   | 013       |
      | CPF           | C (Checkings) | 001       |
      | CNPJ          | S (Savings)   | 022       |
      | CNPJ          | C (Checkings) | 003       |
    

    > **Warning:**
> The `bank_details` parameter is obligatory if the bank code is 104 (Caixa Econômica).

    Including `bank_details` in the payload overrides the self-onboarding process. The API will use the provided data directly instead of requesting it from the payee.

    ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "external_reference": "{{unique_external_reference}}",
    "country": "br",
    "amount": 10,
    "currency_code": "USD",
    "payee": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "document": "{{tax_id}}",
        "document_type": "CPF"
    }
}'
```

    Choose the payment method for your payout request:

            {pix?.label}

        }
      >
    **Identifying the Payee:**

    You can initiate a Pix transfer using one of two methods:

    **Pix using bank account info**: Identify the payee using their bank account details.

    **Pix Key**: Identify the payee using a `pix_key` a unique code linked to their account. (See `target_account` for a list of valid key formats).

      The following example demonstrates a request to send a Pix transaction using the payee's bank account information.

      ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "external_reference": "{{unique_external_reference}}",
    "country": "br",
    "amount": 10,
    "currency_code": "BRL",
    "target": "pix",
    "payee": {
        "document": "{{tax_id}}",
        "document_type": "CPF",
        "name": "Carlos Machado",
        "email": "john.doe@example.com",
        "bank_info": {
            "bank_name": "104  Caixa Econômica",
            "bank_branch": "{{bank_branch}}",
            "bank_account": "{{bank_account}}",
            "account_type": "C",
            "bank_details": "001",
            "bank_ispb": "{{bank_ispb}}"
        }
    }
}'
```
      > **Tip:**
> You can identify the destination bank with either `bank_ispb` or `bank_name`: sending `bank_ispb` alone is enough when `bank_name` is omitted, and sending `bank_name` alone is enough when `bank_ispb` is omitted. At least one of `bank_name` or `bank_ispb` must be provided. We recommend choosing one of them.

      **Identifying the destination bank:**

      The [**/ws/payout/banks**](/api-reference?api=payout&page=post--ws-payout-banks) endpoint returns the accepted `bank_name` values for Brazil. Each entry is prefixed with the bank identifier: the 3-digit COMPE code when the bank has one, or the 8-digit ISPB code when it does not.

      ```json
"brazil": [
  "104  Caixa Econômica",
  "001  Banco do Brasil",
  "11275560  RECARGAPAY IP LTDA."
]
```

      Any of the four combinations below identifies the destination bank. Combinations 1, 3, and 4 show equivalent ways to reach the same bank (Caixa Econômica), while combination 2 illustrates a bank with no COMPE code:

      1. `bank_name` with the COMPE code, as returned by **/ws/payout/banks**.

      ```json
"bank_info": {
  "bank_name": "104  Caixa Econômica",
  "bank_branch": "3708",
  "bank_account": "08251777-6",
  "account_type": "C"
}
```

      2. `bank_name` with the 8-digit ISPB code, as returned by **/ws/payout/banks** for banks that have no COMPE code. EBANX extracts the ISPB from the prefix.

      ```json
"bank_info": {
  "bank_name": "11275560  RECARGAPAY IP LTDA.",
  "bank_branch": "3708",
  "bank_account": "08251777-6",
  "account_type": "C"
}
```

      For these banks the ISPB prefix is optional: the bank name alone also identifies the bank, as long as it matches the name returned by **/ws/payout/banks**.

      ```json
"bank_info": {
  "bank_name": "RECARGAPAY IP LTDA.",
  "bank_branch": "3708",
  "bank_account": "08251777-6",
  "account_type": "C"
}
```

      3. `bank_ispb` only. EBANX resolves the bank and fills `bank_name` for you.

      ```json
"bank_info": {
  "bank_ispb": "00360305",
  "bank_branch": "3708",
  "bank_account": "08251777-6",
  "account_type": "C"
}
```

      4. `bank_name` and `bank_ispb` together. Both values must refer to the same bank.

      ```json
"bank_info": {
  "bank_name": "104  Caixa Econômica",
  "bank_ispb": "00360305",
  "bank_branch": "3708",
  "bank_account": "08251777-6",
  "account_type": "C"
}
```

</TabItem>
      <TabItem value="Pix Key">
      The following example demonstrates a request to send a Pix transaction using the payee's **Pix Key**.

            > **Note:**
> A Pix Key is a unique identifier associated with the payee's account. (See `target_account` for supported key types.)

      ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "external_reference": "{{unique_external_reference}}",
    "country": "br",
    "amount": 10,
    "currency_code": "BRL",
    "target": "pix_key",
    "target_account": "john.doe@example.com",
    "payee": {
        "document": "{{tax_id}}",
        "document_type": "CPF",
        "name": "Carlos Machado",
        "email": "john.doe@example.com"
    }
}'
```

      A successful request returns the following JSON response:

      ```json
{
  "external_reference": "{{unique_external_reference}}",
  "country": "br",
  "amount": "10",
  "currency_code": "BRL",
  "use_payee_hub": false,
  "payee": {
    "document": "{{tax_id}}",
    "document_type": "CPF",
    "name": "Carlos Machado",
    "email": "john.doe@example.com",
    "birthdate": null,
    "address": {
      "zipcode": "80010-010",
      "state": "PR",
      "city": "Curitiba",
      "street_address": "Rua Marechal Deodoro",
      "street_complement": "630"
    }
  },
  "target": "pix_key",
  "target_account": "john.doe@example.com"
}
```
      </TabItem>
    </Tabs>

  </TabItem>
  <TabItem
    value="mercadopago"
    label={
      <TabLabelWithIcon iconSrc={mercadoPago?.icon}>
        {mercadoPago?.label}
      </TabLabelWithIcon>
    }
  >
    For **Mercado Pago** transactions, the `target` parameter must be set to "mercadopago". Additionally, the `target_account` must contain the email address linked to the payee's account.

    ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "external_reference": "{{unique_external_reference}}",
    "country": "br",
    "amount": 10,
    "currency_code": "BRL",
    "target": "mercadopago",
    "target_account": "john.doe@example.com",
    "payee": {
        "document": "{{tax_id}}",
        "document_type": "CPF",
        "name": "John Doe",
        "email": "john.doe@example.com"
    }
}'
```

        TED

    }
  >
    To use **TED (Bank Transfer)** as the payment method, the `target` field needs to be filled in as **"bank_account_ted"** or it can be left as blank.

    ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "external_reference": "{{unique_external_reference}}",
    "country": "br",
    "amount": 10,
    "currency_code": "BRL",
    "target": "bank_account_ted",
    "payee": {
        "document": "{{tax_id}}",
        "document_type": "CPF",
        "name": "Carlos Machado",
        "email": "john.doe@example.com",
        "bank_info": {
            "bank_name": "104  Caixa Econômica",
            "bank_branch": "{{bank_branch}}",
            "bank_account": "{{bank_account}}",
            "account_type": "C",
            "bank_details": "001",
            "bank_ispb": "{{bank_ispb}}"
        }
    }
}'
```

    A successful creation will return a JSON Object with type "success" and a payout object with all the details of the newly created payout.

    ```json
{
  "type": "success",
  "payout": {
    "uid": "{{payout_uid}}",
    "external_reference": "{{unique_external_reference}}",
    "status": "OP",
    "request_date": "2020-09-18 13:26:53",
    "status_date": null,
    "paid_date": null,
    "cancel_date": null,
    "payee": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "554112345678",
      "document": "{{tax_id}}",
      "document_type": "CPF",
      "birthdate": null,
      "bank_info": {
        "bank_name": "104 Caixa Econômica",
        "bank_branch": "{{bank_branch}}",
        "bank_account": "{{bank_account}}",
        "account_type": "C",
        "bank_details": "001"
      }
    },
    "request_amount": 10,
    "request_currency": "USD",
    "request_exchange_rate": 1,
    "debit_amount": 10,
    "debit_fee": 0.15,
    "debit_amount_total": 10.15,
    "debit_currency": "USD",
    "local_tax_amount": "0.12",
    "local_amount_total": "32.88",
    "local_currency": "USD",
    "local_exchange_rate": "3.2997"
  }
}
```

  ### Send commit request to EBANX

    Once the new payout record is created it'll be committed automatically after 6 hours. Or you can use the [**/ws/payout/commit**](/api-reference?api=payout&page=post--ws-payout-commit) endpoint to start the payment process.

    Here's an example of a commit operation using the payout we've just created:

    ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/payout/commit' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "uid": "{{payout_uid}}"
}'
```

    Once the new payout is committed, a JSON Object with type "success" will be returned.

    ```json
{
  "type": "success",
  "message": "Payout has already been committed"
}
```

  ### Congratulations!

    You have successfully **Created a Payout** in Brazil.

## Creating a Payout using the Dashboard

You can also create a payout through our Dashboard in the Overview section of the Payout tab. Click on Create Payout, fill in the payee information, payout amount and click on Create. Additionally, you can create a Mass Payout by sending a spreadsheet to be processed in bulks.

> **BANK BRANCH CODE**
> **Verify the bank branch code.** For many digital banks, such as Nubank,
> [**Inter**](https://ajuda.inter.co/conta-digital-pessoa-fisica-e-mei/qual-e-o-codigo-e-agencia-do-inter),
> and C6, the required branch is typically **0001**. Entering a different number
> may cause the payment to be rejected.

## Available Banks

| Bank Code | Institution Name |
| :--- | :--- |
| **001** | Banco do Brasil S.A. |
| **033** | Banco Santander (Brasil) S.A. |
| **104** | Caixa Econômica Federal |
| **237** | Banco Bradesco S.A. |
| **341** | Itaú Unibanco S.A. |
| **260** | Nu Pagamentos S.A. (Nubank) |
| **077** | Banco Inter S.A. |
| **336** | Banco C6 S.A. |
| **290** | PagSeguro Internet S.A. |
| **380** | PicPay Serviços S.A. |
| **323** | Mercado Pago |
| **212** | Banco Original S.A. |
| **655** | Banco Votorantim (Neon) |
| **041** | Banrisul |
| **070** | BRB – Banco de Brasília |
| **748** | Sicredi |
| **756** | Bancoob (Sicoob) |
| **074** | Banco Safra S.A. |
| **422** | Banco Safra (Carteira Digital) |
| **654** | Banco Digimais (antigo Renner) |
| **218** | Banco BS2 S.A. |
| **069** | BPN Brasil / Crefisa |
| **121** | Banco Agibank S.A. |
| **318** | Banco BMG S.A. |
| **208** | Banco BTG Pactual S.A. |

## Possible Errors

See the [Payout Error Code page](/docs/payout/create-payout/errors/payout-error-codes) to learn more about the possible errors.
## Still need help?

If you still have questions, you can explore the following options:

- **Merchant support:** Contact our support team at [sales.engineering@ebanx.com](mailto:sales.engineering@ebanx.com) for assistance.
- **Not a partner yet?** Complete the [Merchant Signup Form](https://business.ebanx.com/en/request-contact), and our commercial team will reach out to you.