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 confirmed payment is allowed per enrollment cycle. However, if a payment is canceled, you can submit a new payment request within the same 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 -X POST 'https://sandbox.ebanx.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-10 13:05:00",
           "open_date": "2024-01-10 13:00:00",
           "confirm_date": null,        
           "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",
           "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,
           "retries": {
               "retry_status": "LOCKED",
               "available_retries": 0,
               "payment_attempts": [
                   {
                       "attempted_at": "2024-01-10 13:05:00",
                       "attempt_response": "PENDING"
                   }
               ]
           },
           "enrollment": {
               "status": "accepted",
               "merchant_enrollment_code": "{{merchant_enrollment_code}}"
           },
           "subscription": {
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2024-01-01",
               "expiration_date": null,
               "frequency": "monthly",
               "retry": "allow_3R_7D",
               "max_amount_floor": "100.00"
           }
       },
       "status": "SUCCESS"
   }        
   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 'https://sandbox.ebanx.com/ws/cancel' \
   --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 CA for the recurring payment and the details of the cancellation inside the transaction_status node.

   {
       "payment": {
           "hash": "6834b47584a89429eda5c9272f741c54ce0f6c5921aaaaa",
           "country": "br",
           "merchant_payment_code": "1748284533",
           "order_number": null,
           "status": "CA",
           "status_date": "2024-01-10 13:05:00",
           "open_date": "2024-01-10 13:00:00",
           "confirm_date": null,
           "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",
           "instalments": "1",
           "payment_type_code": "pix-automatico",
           "redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=6834b47584a89429eda5c9272f741c54ce0f6c5921aaaaa",
           "pre_approved": false,
           "capture_available": null,
           "transaction_status": {
               "acquirer": "EBANX IP",
               "code": "NOK",
               "description": "Payment cancellation requested by the merchant",
               "description_code": "CANCELED_BY_MERCHANT",
               "details": "The payment was canceled at the merchant's request."
           },
           "enrollment": {
               "status": "accepted",
               "merchant_enrollment_code": "123456789"
           },
           "subscription": {
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2024-01-01",
               "expiration_date": null,
               "frequency": "monthly",
               "retry": "allow_3R_7D",
               "max_amount_floor": "100.00"
           },
           "retries": {
               "retry_status": "ENDED",
               "available_retries": 0,
               "payment_attempts": [
                   {
                       "attempted_at": "2024-01-10 13:05:00",
                       "attempt_response": "FAILED"
                   }
               ]
           }
       },
       "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

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.