Cancelling Pix Automático Payments

Overview

This guide quickly demonstrates how to cancel a pending or open payment in EBANX. We will walk you through the basic steps to achieve this goal using your already existing Direct API integration.

Important:

• A payment cancellation, whether requested by the user or the merchant, does not imply the cancellation of the enrollment.
• Only one payment request can be made per enrollment cycle. If a payment is canceled for the current cycle, no new request can be submitted until the next cycle.
• A payment request can only be canceled by the merchant until 10:00 PM BRT on the day before the expected billing date. After this time, the customer's bank will no longer process cancellation requests.

How it works

To Cancel a payment through EBANX Direct API, please follow the steps below.

1. Make sure that the payment status is equal pending or open

   You can only cancel a payment if its status is equal to (OP) open or (PE) pending. 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 OP or PE for a recurring payment that is eligible for a cancellation.

   {

   "payment": {

   "hash": "{{unique_payment_hash}}",

   "country": "BR",

   "merchant_payment_code": "{{unique_payment_code}}",

   "status": "PE",

   "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 equal to CO (Confirmed) can only be refunded, not canceled.

2. Cancel the payment using /ws/cancel end-point

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

   Parameter	Requirement	Description
   integration_key	Required	Your unique and secret integration key
   hash	Required	The payment hash (EBANX unique identifier)

   Please, check the example below:

   curl -X POST -G 'https://sandbox.ebanxpay.com/ws/cancel' \

   -d 'integration_key=your_test_integration_key' \

   -d 'hash=5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9'

   A successful request will return a JSON response similar to the one below, with the status of the payment updated to CA(canceled)

   {

   "payment": {

   "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9",

   "merchant_payment_code": "1461416920319",

   "order_number": "146",

   "status": "CA",

   "status_date": "2014-11-26 17:34:11",

   "open_date": "2014-11-25 10:45:56",

   "confirm_date": null,

   "transfer_date": null,

   "amount_br": "204.45",

   "amount_ext": "87.00",

   "amount_iof": "0.00",

   "currency_rate": "2.3500",

   "currency_ext": "USD",

   "due_date": "2014-12-2",

   "instalments": "1",

   "payment_type_code": "pix-automatico",

   "pre_approved": false,

   "capture_available": null

   },

   "operation": "cancel",

   "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?

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.