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.

How it works

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 statis is CO (confirmed) and start the refund process.

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

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 the same bank account of their Pix Automatico set up), 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 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 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 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, 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 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:

    ParameterRequirementDescription
    integration_keyRequiredYour unique and secret integration key
    operationRequiredRequired
    hashRequiredThe payment hash (EBANX unique identifier)
    amountRequiredThe amount to be refunded; expressed in the original payment currency.
    descriptionOptionalDescription of the refund reason.
    merchant_refund_codeOptionalThe 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.

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 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"
}
note

Pix Automático will go live on June 16, 2025. In the meantime, you can use our Sandbox environment, available since December 1, 2024!

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options:

Edit this page
Last updated on by Sarah Nicolau
On This Page