Version: current

Create a Payout

About this guide

This guide quickly demonstrates how to create a payout in EBANX. We will walk you through the basic steps to achieve this goal using your already existing Direct API integration.

How it works

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

  1. Make sure you have all the mandatory fields in your request

    There are a few key parameters you need to provide to create a payout. Check the table below for more details.

    FieldDescription
    integration_keyYour unique and secret integration key.
    external_referenceThe unique payout ID provided by you.
    countryThe two-letter country code for the customer country. Available countries: mx (Mexico), cl (Chile), br (Brazil) and co (Colombia)
    amountThe amount in the specified currency (currency_code).
    currency_codeThree-letter code of the payout currency. Available currency codes: USD, MXN (Mexico), CLP (Chile), BRL (Brazil) and COP (Colombia)
    payeeA JSON object containing the details of the payee of your request.
    Payee Details

    Note that you can either provide all the information of the payee directly on you payout creation request or create the payee record in advance, using the /ws/payee/create endpoint, and simply provide the payee's document number in the payout request.

  2. Send your 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[birthdate]=1977-05-25' \
    -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[terms_accepted_at]=2020-04-20 10:20:12'

    If you have created your payee in advance, simply provide the document number on your payout request:

    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[document]=85351346893' \
    -d 'payee[terms_accepted_at]=2020-04-20 10:20:12'

    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.

    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' \
    -d 'payee[birthdate]=1977-05-25' \
    -d 'payee[terms_accepted_at]=2020-04-20 10:20:12'

    For Colombia only you have the option to create a payout for Nequi EWallet.

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'target=ewallet_nequi' \
    -d 'ewallet_account_id=1234567890' \
    -d 'country=co' \
    -d 'amount=100' \
    -d 'currency_code=COP' \
    -d 'payee[name]=Han Solo' \
    -d 'payee[email]=chew@bac.ca' \
    -d 'payee[document]=85351346893' \
    -d 'payee[document_type]=cc' \
    -d 'payee[birthdate]=1977-05-25' \
    -d 'payee[terms_accepted_at]=2020-04-20 10:20:12'

    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": "1977-05-25",
    "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": "9.96",
    "debit_fee": "0.15",
    "debit_amount_total": "10.11",
    "debit_currency": "USD"
    }
    }
  3. Send a 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": "You've successfully started the Payout payment process!"
    }

Creating a Payout via 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.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill ou this form and our comercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Last updated on by Fernando Pankiewicz Gomes