Version: current

Refund a payment

About this guide

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

How it works

Basically, the refund process can only be triggered to already confirmed payments generated with your account. Payments with status open (OP) or pending (PE) cannot be refunded. To understand a little bit more how it works, take a look in the refund flow in the following diagram:

EBANX Refund flow

  1. The merchant requests the refund through the Dashboard or the API.
  2. This refund request gets directly into EBANX refund queue, marked as Requested.
  3. EBANX then acknowledges the refund and the refund is marked as Pending.
  4. When the customer receives the money back (in his bank account or through his credit card), the refund transitions its state to Confirmed.
note

When the refund is Requested or Pending, it can be cancelled by the merchant.

Please, keep in mind:

  • Each payment can have many refunds, given that the sum of their amounts does not exceed the original payment amount. Cancelled refunds do not count toward this sum;
  • Only confirmed payments (CO) can be refunded;
  • The currency of the refund is the same as the original payment;
  • Refunds are notified when the refund is pending and an email is sent to the customer asking for bank information and when the refund is confirmed;

To Refund a payment through EBANX Direct API, please follow the steps below.

  1. Make sure that the payment status is equal confirmed

    You can only refund a payment if its status is equal to (CO) confirmed. You can check the status of your payment using the end-point ws/query. You can learn more about this end-point in this quick guide.

    Confirmed payments

    Please, note that payments with status equal to (OP) open or (PE) pending can only be canceled, not refunded.

  2. Refund the payment using /ws/refund end-point

    To refund a payment, you just need to call the end-point /ws/refund (from your server) with the following required fields:

    ParameterDescription
    integration_keyYour unique and secret integration key.
    operationThe available operations are: request to request a new refund or cancel to cancel a refund.
    hashThe payment hash (EBANX unique identifier).
    amountThe amount to be refunded; expressed in the original payment currency.
    descriptionDescription of the refund reason.
    merchant_refund_codeThe ID of the refund on the merchant system. Unique
    refund_idThe ID of the refund to be cancelled.

    Please, check the example below:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/refund' \
    -d 'integration_key=your_test_integration_key' \
    -d 'operation=request' \
    -d 'merchant_refund_code=787653' \
    -d 'hash=5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221' \
    -d 'amount=100.00' \
    -d 'description=Order did not arrive'

    A successful request will return a JSON response similar to the one below.

    {
    "payment": {
    "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
    "pin": "253639240",
    "country": "br",
    "merchant_payment_code": "9dwdwdw1e31c4c234",
    "order_number": null,
    "status": "CO",
    "status_date": "2018-04-19 20:57:07",
    "open_date": "2018-04-19 20:56:42",
    "confirm_date": "2018-04-19 20:57:07",
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2018-04-22",
    "instalments": "1",
    "payment_type_code": "itau",
    "pre_approved": false,
    "capture_available": null,
    "refunds": [
    {
    "id": "68682",
    "merchant_refund_code": null,
    "status": "RE",
    "request_date": "2018-04-19 21:00:06",
    "pending_date": null,
    "confirm_date": null,
    "cancel_date": null,
    "amount_ext": "100.00",
    "description": "Testing notifications"
    }
    ]
    },
    "status": "SUCCESS"
    }
    Complete EBANX Direct API Reference

    The complete API reference for the end-point ws/refund can be found here. We strongly recommend you to take a look in all the available options and examples.

  3. Add bank details to the refund request

    Availability

    Please, note that this feature is only available in Crossborder model in Brazil, Chile, Colombia and Mexico

    You can add bank details directly to the refund request. To do so, you'll need to provide the following extra parameters

    ParameterDescription
    bank_info.bank_nameBank Name
    bank_info.bank_branchBank branch. The branch can have a digit. If have so, the digit should be separated with a hyphen
    bank_info.bank_accountAccount number, if have digit should be separated with a hyphen
    bank_info.account_typeAccount type
    bank_info.bank_detailsOnly when the bank is 104 Caixa Econômica
    bank_info.bank_account_holder_documentBank account holder document: CPF or CNPJ
    bank_info.bank_account_holder_nameBank account holder name

    Please, check the example below:

    curl --location --request POST 'http://api.ebanxpay.com/ws/refund' \
    -d 'integration_key=INTEGRATION_KEY' \
    -d 'hash=PAYMENT_HASH' \
    -d 'operation=request' \
    -d 'amount=1.00' \
    -d 'description=refund' \
    -d 'merchant_refund_code=CODE' \
    -d 'bank_info[bank_name]=260 Nu Pagamentos S.A.' \
    -d 'bank_info[bank_branch]=0001' \
    -d 'bank_info[bank_account]11111111-2' \
    -d 'bank_info[account_type]=C' \
    -d 'bank_info[bank_account_holder_document]=85351346893' \
    -d 'bank_info[bank_account_holder_name]=José Silva' \

    A successful request will return a JSON response similar to the one below.

    {
    "payment": {
    "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
    "pin": "253639240",
    "country": "br",
    "merchant_payment_code": "123456789",
    "order_number": null,
    "status": "CO",
    "status_date": "2018-04-19 20:57:07",
    "open_date": "2018-04-19 20:56:42",
    "confirm_date": "2018-04-19 20:57:07",
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2018-04-22",
    "instalments": "1",
    "payment_type_code": "boleto",
    "pre_approved": false,
    "capture_available": null,
    "refunds": [
    {
    "id": "68682",
    "merchant_refund_code": null,
    "status": "RE",
    "request_date": "2018-04-19 21:00:06",
    "pending_date": null,
    "confirm_date": null,
    "cancel_date": null,
    "amount_ext": "100.00",
    "description": "Testing refund"
    }
    ]
    },
    "status": "SUCCESS"
    }

Canceling a refund request

If the refund is no more needed, you can also cancel its request using our APIs. A refund can be cancelled only if its status is equal to requested (RE) or pending (PE). If everything goes well the refund will be immediately cancelled.

note

If a refund is cancelled, the customer will not receive the money and the merchant will not be charged. Customers are NOT notified about the refund cancellation.

To cancel a refund through EBANX Direct API, you just need to call the same end-point /ws/refund with the parameter operation equal to cancel as wel as its merchant_refund_code.

Please, check the example below:

curl -X POST 'https://sandbox.ebanxpay.com/ws/refund' \
-d 'integration_key=your_test_integration_key' \
-d 'operation=cancel' \
-d 'merchant_refund_code=3784756'
{
"payment": {
"hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
"pin": "253639240",
"country": "br",
"merchant_payment_code": "9dwdwdw1e31c4c234",
"order_number": null,
"status": "CO",
"status_date": "2018-04-19 20:57:07",
"open_date": "2018-04-19 20:56:42",
"confirm_date": "2018-04-19 20:57:07",
"transfer_date": null,
"amount_br": "100.38",
"amount_ext": "100.00",
"amount_iof": "0.38",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"due_date": "2018-04-22",
"instalments": "1",
"payment_type_code": "itau",
"pre_approved": false,
"capture_available": null,
"refunds": [
{
"id": "68682",
"merchant_refund_code": "3784756",
"status": "CA",
"request_date": "2018-04-19 21:00:06",
"pending_date": null,
"confirm_date": null,
"cancel_date": "2018-04-20 21:00:06",
"amount_ext": "100.00",
"description": "Test transaction"
}
]
},
"status": "SUCCESS"
}

Refunds using Dashboard

Alternativelly, you can also refund a confirmed payment or cancel a refund using your EBANX Dashboard.

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.
Last updated on by “ElderBalsani