Refunding Pix Automático Payments

The refund process can only be triggered for payments that have already been confirmed, payments with a pending status were not yet paid and cannot be refunded. Make sure the payment status is Confirmed (CO) and start the refund process.

To learn more about how it works, refer to the refund flow diagram below:

How it works

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 the same bank account of their Pix Automatico set up), the refund transitions its state to Confirmed.

Guidelines

• Each payment can have multiple 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 (CO) payments can be refunded.
• The currency of the refund is the same as the original payment.
• Refunds are notified when the refund is pending and when the refund is confirmed.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

Instructions

To refund a Pix Automático payment, follow the steps below.

1. Ensure payment status is confirmed

   You can only refund a payment if its status is equal to Confirmed (CO).

   You can check the status of your payment using the end-point ws/query, refering to the hash provided in the payment response.

   curl POST 'https://sandbox.ebanxpay.com/ws/query' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "{{integration_key}}",
       "hash": "{{unique_payment_hash}}"
   
   }'

   A successful request will return a JSON response like the one below, with a status of CO for a recurring payment that is eligible for a refund.

   {
       "payment": {
           "hash": "{{unique_payment_hash}}",
           "country": "BR",
           "merchant_payment_code": "{{unique_payment_code}}",
           "status": "CO",
           "status_date": "2024-01-17 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",
           "amount_ext_requested": "0.00",
           "currency_rate": "1.0000",
           "currency_ext": "BRL",
           "due_date": "2024-01-17",
           "instalments": "1",
           "payment_type_code": "pix-automatico",
           "redirect_url": "00020101021226740014br.gov.bcb.pix2552pix.ebanx.com\/qr\/v2\/F2D9448AA5B94ED3450A4A8933748F5952040000556345643602BR5911EbanxLTDA.6008CURITIBA62070503***63045022",
           "pre_approved": false,
           "capture_available": null,
           "customer": {
               "document": "{{customer_document}}",
               "email": "{{customer_email}}",
               "name": "{{customer_name}}",
               "birth_date": "1992-08-15",
               "address": "",
               "street_number": "",
               "street_complement": "",
               "city": "",
               "state": "",
               "zipcode": "",
               "country": "BR",
               "phone_number": ""
           },
           "single_transaction": {
               "amount_local": "0.00",
               "amount_crossborder": "19.90"
           },
           "enrollment": {
               "merchant_enrollment_code": "{{merchant_enrollment_code}}"
           }
       }
   }
   Confirmed payments

   Please, note that payments with status Pending (PE) can only be canceled, not refunded.

2. Refund the payment

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

   Parameter	Requirement	Description
   integration_key	Required	Your unique and secret integration key
   operation	Required	Required
   hash	Required	The payment hash (EBANX unique identifier)
   amount	Required	The amount to be refunded; expressed in the original payment currency.
   description	Optional	Description of the refund reason.
   merchant_refund_code	Optional	The unique ID of the refund on the merchant system.

   Please, check the example below:

   curl -X POST \
     --location 'https://sandbox.ebanxpay.com/ws/refund' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "operation": "request",
       "hash": "{{unique_payment_hash}}",
       "amount": "10.00",
       "description": "Order did not arrive"
       "merchant_refund_code": "{{unique_refund_code}}"
     }'

   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": "{{unique_refund_code}}",
             "status": "RE",
             "request_date": "2024-01-27 03:00:00",
             "pending_date": null,
             "confirm_date": null,
             "cancel_date": null,
             "amount_ext": "10.00",
             "description": "Order did not arrive"
           }
         ]
      },
      "status": "SUCCESS"
   }

   The payment will be refunded to the bank account associated with its Pix Automático enrollment.

3. Congratulations!

   You have succesfully integrated Refunded a Pix Automático payment.

   For more information, refer to the

   Direct API reference guidechevron_right

Cancel a Refund

A refund request or pending refund can be canceled by the merchant.

Follow the steps below.

1. Call the same /ws/refund API

   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 and refer to its merchant_refund_code.

   Please, check the example below:

   curl -X POST \
     --location 'https://sandbox.ebanxpay.com/ws/refund' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "operation": "cancel",
       "merchant_refund_code": "{{unique_refund_code}}"
     }'

   A successful response will look like the one below, note the refund status is updated to CA and we also add the cancel_date.

   {
      "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": "CA",
             "request_date": "2024-01-27 03:00:00",
             "pending_date": null,
             "confirm_date": null,
             "cancel_date": "2024-01-27 04:00:00",
             "amount_ext": "17.90",
             "description": "Test Refund"
           }
         ]
      },
      "status": "SUCCESS"
   }

2. Congratulations!

   You have succesfully Cancelled a Pix Automático refund request.

   For more information, refer to the

   Direct API reference guidechevron_right

Product Launch Date

Pix Automático will be available starting June 16, 2025. In the meantime, you can test and explore the features using our Sandbox environment, which has been live since December 1, 2024.

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

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.