Cancelling Pix Automático Payments

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.

Requirements

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

Instructions

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

1. Ensure the payment status is pending or open

   You can only cancel a payment if its status is equal to Open (OP) or Pending (PE). 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

   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 EBANX 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_ebanx_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"
   }

3. Congratulations!

   You have succesfully Cancelled a recurring Pix Automático psayment.

   For more information, refer to the

   Direct API reference guidechevron_right

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

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.

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.