Version: current

Create payout with existing Payee

About this page

This guide quickly demonstrates how to create a payout with existing payee (created by ws/payee/create) 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. 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)
    payee_uuidPayee uuid received on payee create endpoint

  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_uuid=11bfcdc3-f323-4dd1-becc-a75235857fed' \

    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"
    }
    }

    On the other hand, if necessary, you can send the payment to this payee but on a different bank account or with a different payment method.

    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_uuid=11bfcdc3-f323-4dd1-becc-a75235857fed' \
    -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' \
    Bank Information Update

    Note that when you send payee bank information the payee will be updated with the new bank data and this bank account will be considered the standard for future payout create with payee_uuid. That's saying: a payee can only have registered one active account per payment method.

    You can either pass an APM target with respective target_account and even if the payee already has bank information registered, the target data will be considered for this payout.

    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 'target=mercadopago' \
    -d 'target_account=chew@bac.ca' \
    -d 'payee_uuid=11bfcdc3-f323-4dd1-becc-a75235857fed' \

    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": null,
    },
    "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",
    "target": "mercadopago",
    "target_account": "chew@bac.ca"
    }
    }

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 our this form and our commercial 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.
Edit this page
Last updated on by Matheus Aeroso
On this page