At EBANX, refunds allow merchants to return funds to customers for confirmed payments. The refund process is integrated directly into the EBANX Direct API, giving you the ability to manage refunds efficiently from your existing platform. It's important to note that only payments with a confirmed (CO) status can be refunded, meaning transactions in an open (OP) or pending (PE) state must first be confirmed before they are eligible for refund processing.
Features
- Full and partial refunds - Supports both full and partial refunds, giving merchants flexibility.
- API-driven - Refunds are handled through the Direct API, enabling automated requests without manual intervention.
- Compliant with local rules - Comply with local regulations in different countries.
How it works
Step by step
- 1The merchant requests refund through the Dashboard or the API.
- 2The request is placed into EBANX refund queue, marked as Requested.
- 3EBANX acknowledges the refund, and it is marked as Pending.
- 4When the customer receives the money (in bank account or credit card), the refund transitions to Confirmed.
Requirements
- API credentials: Ensure you have an EBANX integration key. If not, complete the Merchant Signup Form.
Guidelines
- Each payment can have multiple refunds, provided that the total refunded amount does not exceed the original payment amount.
- Cancelled refunds are excluded from this total.
- Not all payment methods support partial refunds.
- Only confirmed payments are eligible for refunds. Open or pending transactions cannot be refunded.
- The refund will be issued in the same currency as the original payment.
- Refunds trigger notifications at two points:
- When the refund is pending, an email is sent to the customer requesting their bank information.
- When the refund is confirmed, completing the process.
- When a refund is requested or pending, it can be cancelled by the merchant.
Instructions
To refund a payment, follow the steps below.
Verify payment status
You can only process a refund if the payment status is confirmed (CO). To verify the status of your payment, use the
ws/queryendpoint. For more details on how to use this endpoint, refer to our Retrieve Payment guide.Confirmed paymentsPlease note that payments with the status open (OP) or pending (PE) are only eligible for cancellation, not refunds. Refunds can only be issued for payments that have been confirmed (CO).
Issue a refund
To refund a payment, call the
/ws/refundDirect API endpoint and provide the required fields.Parameter Description integration_key Your EBANX integration key. operation requestto initiate a new refund, orcancelto revoke an existing request.hash Unique payment hash from EBANX amount The amount to be refunded, expressed in the original payment currency. description Description of the refund reason. merchant_refund_code Unique ID of the refund on the merchant system.
optionalSample request
Use the following example to initiate a refund request.
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/refund' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
"amount": "100.00",
"description": "Order did not arrive"
"merchant_refund_code": "787653", // Optional.
}'Sample response
Each request returns a response similar to the example below.
{
"payment": {
"hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
"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", // Unique. Required to cancel the refund.
"merchant_refund_code": "787653", // If provided in the request.
"status": "RE",
"request_date": "2018-04-19 21:00:06",
"pending_date": null,
"confirm_date": null,
"cancel_date": null,
"amount_ext": "100.00",
"description": "Order did not arrive"
}
]
},
"status": "SUCCESS"
}API ReferenceFor detailed information about
ws/refund, refer to the API reference guide.Congratulations!
You have completed the necessary steps to create a refund.
Extra parameters
You can add bank details directly to the refund request by providing extra parameters.
Bank details
The following bank paramters are available.
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 Availability - Bank DetailsThis feature is only available in Crossborder model in Brazil, Chile, Colombia and Mexico
Sample request with bank details
Use the following example to initiate a refund request.
curl -X POST \
--location 'http://sandbox.ebanx.com/ws/refund' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
"amount": "100.00",
"description": "refund",
"merchant_refund_code": "787653", // Optional
"bank_info": {
"bank_name": "260 Nu Pagamentos S.A.",
"bank_branch": "0001",
"bank_account": "11111111-2",
"account_type": "C",
"bank_account_holder_document": "85351346893",
"bank_account_holder_name": "José Silva"
}
}'Sample response
Each request returns a response similar to the example below.
{
"payment": {
"hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
"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": "boleto",
"pre_approved": false,
"capture_available": null,
"refunds": [
{
"id": "68682",
"merchant_refund_code": "787653",
"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"
}
Cancelling a refund
If the refund is no longer necessary, you can cancel the request via the API. A refund can only be canceled if its status is requested (RE) or pending (PE). Upon successful execution, the refund will be canceled immediately.
When a refund is canceled, the customer will not receive the funds, and the merchant will not be charged. Please note that customers are not notified about the cancellation of a refund.
Example request to cancel a refund
To cancel a refund call the
/ws/refundendpoint and set the following parameters.- Set
operationto cancel - Set
refund_idto the refund id.
Use the following example to initiate a cancellation request.
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/refund' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "cancel",
"refund_id": "68682"
}'- Set
Response
Each request returns a response similar to the example below.
{
"payment": {
"hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
"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": "787653",
"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"
}Congratulations!
You have succesfully canceled a refund.
Refunds using dashboard
Alternatively, you can process a refund directly through your EBANX Dashboard.
Resources
Use the following resources when testing in your sandbox environment.
Sample Cards
Click here to view mock card data to validate your payment integration.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
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.