Skip to main content

Create a Payout

This guide provides a quick walkthrough for creating a payout with EBANX, using your existing Direct API integration to complete the process step by step.

Instructions​

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

  1. Define request parameters

    Provide the required parameters listed below to create a payout.

    FieldDescription
    integration_keyYour EBANX integration key.
    external_referenceThe unique payout ID provided by you.
    countryThe two-letter country code for the customer country. In this case, we'll show the method to br (Brazil)
    amountThe amount in the specified currency (currency_code).
    currency_codeThree-letter code of the payout currency. In this case, we'll use BRL (Brazil)
    payeeA JSON object containing the details of the payee of your request.
    Payee Details

    You can either include all payee details in the payout request, or create the payee in advance using the /ws/payee/create endpoint and reference them by document number.

    Document Types Allowed

    These document types are used to identify payees or shareholders.

    Document typeDescription
    CPFThe CPF is a document with an 11 digits number.
    CNPJThe CNPJ is a document with a 14 digits number that identifies a company.

  2. Send payout request to EBANX

    To create a new Payout, you will use the /ws/payout/create endpoint.

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

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'country=br' \
    -d 'amount=10' \
    -d 'currency_code=USD' \
    -d 'payee[name]=Han Solo' \
    -d 'payee[email]=chew@bac.ca' \
    -d 'payee[phone]=+554112345678' \
    -d 'payee[document]=85351346893' \
    -d 'payee[document_type]=cpf' \
    -d 'payee[bank_info][bank_name]=104  Caixa Econômica' \
    -d 'payee[bank_info][bank_branch]=3708' \
    -d 'payee[bank_info][bank_account]=08251777-6' \
    -d 'payee[bank_info][account_type]=C' \
    -d 'payee[bank_info][bank_details]=001' \
    -d 'payee[address][zipcode]=80320070' \
    -d 'payee[address][state]=PR' \
    -d 'payee[address][city]=Curitiba' \
    -d 'payee[address][street_address]=Fake Street' \
    -d 'payee[address][street_complement]=123'

    For Brazil only you have the option of entering only a portion of the payee's information, and the rest of the information can be filled by the payee herself via an email that will be automatically sent requesting the remaining necessary information.

    The bank_details key for 104 Caixa Econômica is not mandatory.

    When bank_details is empty or not the key is not sent, it will be filled with a value according the table:

    Document typeAccount TypeOperation
    CPFS (Savings)013
    CPFC (Checkings)001
    CNPJS (Savings)022
    CNPJC (Checkings)003

    In other hand, when bank_details key with value is sent, the processing to fill it won't be triggered and the value sent will be assumed.

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'country=br' \
    -d 'amount=10' \
    -d 'currency_code=USD' \
    -d 'payee[name]=Han Solo' \
    -d 'payee[email]=chew@bac.ca' \
    -d 'payee[document]=85351346893' \
    -d 'payee[document_type]=cpf'

    For the use of the MercadoPago payment method, follow the example below. The target field needs to be filled in as mercadopago and the target_account can have the email, referring to the MercadoPago account. Available for Brazil:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'country=br' \
    -d 'amount=10' \
    -d 'currency_code=BRL' \
    -d 'target=mercadopago' \
    -d 'target_account=chew@bac.ca' \
    -d 'payee[document]=85351346893' \
    -d 'payee[document_type]=CPF' \
    -d 'payee[name]=Han Solo' \
    -d 'payee[email]=chew@bac.ca'

    To create a payout for an organization entity (company) you should send additional fields holding the shareholders data:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'country=br' \
    -d 'amount=10' \
    -d 'currency_code=USD' \
    -d 'payee[name]=Han Solo' \
    -d 'payee[email]=chew@bac.ca' \
    -d 'payee[phone]=+554112345678' \
    -d 'payee[document]=95575888000105' \
    -d 'payee[document_type]=cnpj' \
    -d 'payee[bank_info][bank_name]=104  Caixa Econômica' \
    -d 'payee[bank_info][bank_branch]=3708' \
    -d 'payee[bank_info][bank_account]=08251777-6' \
    -d 'payee[bank_info][account_type]=C' \
    -d 'payee[bank_info][bank_details]=001' \
    -d 'payee[address][zipcode]=80320070' \
    -d 'payee[address][state]=PR' \
    -d 'payee[address][city]=Curitiba' \
    -d 'payee[address][street_address]=Fake Street' \
    -d 'payee[address][street_complement]=123' \
    -d 'payee[shareholders][0][name]=Roberto Carlos da Silva' \
    -d 'payee[shareholders][0][document]=58017604076' \
    -d 'payee[shareholders][0][document_type]=CPF' \
    -d 'payee[shareholders][0][email]=roberto.carlos@mail.com.br' \
    -d 'payee[shareholders][0][zipcode]=69926970' \
    -d 'payee[shareholders][0][state]=AC' \
    -d 'payee[shareholders][0][city]=Bujari' \
    -d 'payee[shareholders][0][address]=Rua Adoniran Barbosa 118' \
    -d 'payee[shareholders][0][complement]=Centro' \
    -d 'payee[shareholders][0][ownership_percent]=51' \
    -d 'payee[shareholders][1][name]=Vanessa Ribeiro' \
    -d 'payee[shareholders][1][document]=57191825006' \
    -d 'payee[shareholders][1][document_type]=CPF' \
    -d 'payee[shareholders][1][email]=vanessa@mail.com.br' \
    -d 'payee[shareholders][1][zipcode]=69926970' \
    -d 'payee[shareholders][1][state]=AC' \
    -d 'payee[shareholders][1][city]=Bujari' \
    -d 'payee[shareholders][1][address]=Rua Adoniran Barbosa 118' \
    -d 'payee[shareholders][1][complement]=Centro' \
    -d 'payee[shareholders][1][ownership_percent]=49'

    For organizations, some fields are mandatory in shareholder set:

    • name
    • document_type
    • document

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

    {
      "type": "success",
      "payout": {
        "uid": "a1352f5341c3c8c1e40ea9c06715f05778ff35ee",
        "external_reference": "PAYOUT_EBANX_04",
        "status": "OP",
        "request_date": "2020-09-18 13:26:53",
        "status_date": null,
        "paid_date": null,
        "cancel_date": null,
        "payee": {
          "name": "Han Solo",
          "email": "chew@bac.ca",
          "phone": "554112345678",
          "document": "85351346893",
          "document_type": "CPF",
          "birthdate": null,
          "bank_info": {
            "bank_name": "104 Caixa Econ\u00f4mica",
            "bank_branch": "3708",
            "bank_account": "8251777-6",
            "account_type": "C",
            "bank_details": "001"
          }
        },
        "request_amount": "10.00",
        "request_currency": "USD",
        "request_exchange_rate": "1.0000",
        "debit_amount": "10.00",
        "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"
      }
    }

  3. 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 endpoint to start the payment process.

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

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/commit' \
        -d 'integration_key=your_test_integration_key' \
        -d 'uid=0e495f7a4409c032d54376084b10b9c771e9b39f0'

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

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

  4. Congratulations!

    You have succesfully Created a Payout in Brazil.

Creating a Payout using Dashboard​

You can also create a payout through your Dashboard in the Overview section of the Payout tab. Click on Create Payout, fill in the payee information, payout amount and click Create. Additionally, you can create a Mass Payout for up to 600 payouts.

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: