Refunding Pix Automático Payments
Overview
This guide quickly demonstrates how to refund a confirmed Pix Automático payment in EBANX. We will walk you through the basic steps to achieve this goal using your already existing Direct API integration.
Availability
Pix Automático integration through Direct API will be available in Brazil only.
What you will need
A Sandbox Account
As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.
Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!
Sign up for an EBANX Sandbox Account here
How it works
Basically, the refund process can only be triggered to already confirmed payments generated with your account. Payments with status 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.Confirmed payments
Please, note that payments with
status(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={{integration_key}}' \-d 'operation=request' \-d 'merchant_refund_code={{unique_refund_code}}' \-d 'merchant_payment_code={{unique_payment_code}}' \-d 'amount=17.90' \-d 'description=Test Refund'A successful request will return a JSON response similar to the one below.
{"payment": {"hash": "{{unique_payment_hash}}","country": "br","merchant_payment_code": "{{unique_payment_code}}","merchant_enrollment_code": "{{unique_enrollment_code}}","status": "CO","status_date": "2024-01-27 03:00:00","open_date": "2024-01-10 13:00:00","confirm_date": "2024-01-17 03:00:00","transfer_date": null,"amount_br": "19.90","amount_ext": "19.90","amount_iof": "0.00","currency_rate": "1.0000","currency_ext": "BRL","due_date": "2024-01-17","payment_type_code": "pix-automatico","pre_approved": false,"refunds": [{"id": "68682","merchant_refund_code": null,"status": "RE","request_date": "2024-01-27 03:00:00","pending_date": null,"confirm_date": null,"cancel_date": null,"amount_ext": "17.90","description": "Test Refund"}]},"status": "SUCCESS"}The payment will be refunded to the bank account associated with its Pix Automático enrollment.
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:
note
Pix Automático goes live on June 16th 2025. Stay tuned for Sandbox Environment availability on December 1st 2024!
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Customer support: Contact our support team at integration@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.