Create a Payout for Colombia | EBANX Developers Academy

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.

Define your 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 use co (Colombia)
`amount`	The amount in the specified currency (currency_code).
`currency_code`	Three-letter code of the payout currency. Available currency codes: USD, MXN (Mexico), CLP (Chile), BRL (Brazil) and COP (Colombia)
`payee`	A 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 type	Description
CC	Citizenship card.
CE	Foreigner ID.
TI	Identity card.
NTI	Tax identification number.

If you need send the CE document type, it's mandatory to send payee_document_date_issue in the format YYYY-MM-DD.

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=co' \
-d 'amount=10' \
-d 'currency_code=COP' \
-d 'payee[name]=Han Solo' \
-d 'payee[email]=chew@bac.ca' \
-d 'payee[phone]=+57112345678' \
-d 'payee[document]=853513468' \
-d 'payee[document_type]=CE' \
-d 'payee[payee_document_date_issue]=2001-11-01' \
-d 'payee[bank_info][bank_name]=1006  Banco Corpbanca Colombia S.A' \
-d 'payee[bank_info][bank_account]=007520025' \
-d 'payee[bank_info][account_type]=C' \
-d 'payee[address][zipcode]=110111' \
-d 'payee[address][state]=Bogota' \
-d 'payee[address][city]=DC' \
-d 'payee[address][street_address]=Fake Street' \
-d 'payee[address][street_complement]=123'

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 'target_account=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]=853513468' \
-d 'payee[document_type]=CC'

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=co' \
-d 'amount=10' \
-d 'currency_code=COP' \
-d 'payee[name]=Han Solo' \
-d 'payee[email]=chew@bac.ca' \
-d 'payee[phone]=+57112345678' \
-d 'payee[document]=9557588800' \
-d 'payee[document_type]=NIT' \
-d 'payee[bank_info][bank_name]=1006  Banco Corpbanca Colombia S.A' \
-d 'payee[bank_info][bank_account]=007520025' \
-d 'payee[bank_info][account_type]=C' \
-d 'payee[address][zipcode]=110111' \
-d 'payee[address][state]=Bogota' \
-d 'payee[address][city]=DC' \
-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]=5801760407' \
-d 'payee[shareholders][0][document_type]=CC' \
-d 'payee[shareholders][0][email]=roberto.carlos@mail.com.br' \
-d 'payee[shareholders][0][zipcode]=110111' \
-d 'payee[shareholders][0][state]=BogotaDC' \
-d 'payee[shareholders][0][city]=Fake city' \
-d 'payee[shareholders][0][address]=Fake street' \
-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]=571918250' \
-d 'payee[shareholders][1][document_type]=CC' \
-d 'payee[shareholders][1][email]=vanessa@mail.com.br' \
-d 'payee[shareholders][1][zipcode]=110111' \
-d 'payee[shareholders][1][state]=BogotaDC' \
-d 'payee[shareholders][1][city]=Fake city' \
-d 'payee[shareholders][1][address]=Fake Sstreet' \
-d 'payee[shareholders][1][complement]=Centro' \
-d 'payee[shareholders][1][ownership_percent]=49'

For organizations, some fields are mandatory in shareholder set:

name
document
document_type

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": "57112345678",
      "document": "853513468",
      "document_type": "CC",
      "birthdate": null,
      "bank_info": {
        "bank_name": "1006  Banco Corpbanca Colombia S.A",
        "bank_branch": "",
        "bank_account": "007520025",
        "account_type": "C",
        "bank_details": ""
      }
    },
    "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"
  }
}

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"
}
```
Congratulations!
You have succesfully Created a Payout in Colombia.

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.

Still need help?

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

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

Create a Payout

Instructions​

Define your parameters

Send payout request to EBANX

Send commit request to EBANX

Congratulations!

Creating a Payout via Dashboard​

Still need help?

Instructions

Creating a Payout via Dashboard