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:
- The merchant requests the refund through the Dashboard or the API.
- This refund request gets directly into EBANX refund queue, marked as Requested.
- EBANX then acknowledges the refund and the refund is marked as Pending.
- 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.
Make sure that the payment status is equal confirmed
You can only refund a payment if its
statusis equal to (CO) confirmed. You can check the status of your payment using the end-pointws/query. You can learn more about this end-point in this quick guide.Confirmed payments
Please, note that payments with
statusequal to (OP) open or (PE) pending can only be canceled, not refunded.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:Parameter Description integration_key Your unique and secret integration key. operation The available operations are: requestto request a new refund orcancelto cancel a refund.hash The payment hash (EBANX unique identifier). amount The amount to be refunded; expressed in the original payment currency. description Description of the refund reason. merchant_refund_code The ID of the refund on the merchant system. Unique refund_id The 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/refundcan be found here. We strongly recommend you to take a look in all the available options and examples.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
Parameter Description bank_info.bank_name Bank Name bank_info.bank_branch Bank branch. The branch can have a digit. If have so, the digit should be separated with a hyphen bank_info.bank_account Account number, if have digit should be separated with a hyphen bank_info.account_type Account type bank_info.bank_details Only when the bank is 104 Caixa Econômica bank_info.bank_account_holder_document Bank account holder document: CPF or CNPJ bank_info.bank_account_holder_name Bank 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:
Refunds using Dashboard
Alternativelly, you can also refund a confirmed payment or cancel a refund using your EBANX Dashboard.
Refund simulator for Sandbox Environment
For tests in sandbox environment, it was developed 3 extra endpoints to help simulating all steps after a refund is made by /ws/refund endpoint.
To approve a refund, moving from requested (RE) status to pending (PE), you can use the /ws/simulateRefund/approveRefund endpoint.
Please, check the example below:
To fill a refund with bank data, moving from pending (PE) status to confirmed (CO), you can use the /ws/simulateRefund/fillRefundForm endpoint.
Please, check the example below:
To set a refund as paid, moving from confirmed (CO) status to paid (PA), you can use the /ws/simulateRefund/setAsPaid endpoint.
Please, check the example below:
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.