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 authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, 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, referring to the hash provided in the payment response.

   Shell

   curl -X POST \
     --location '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.

   JSON

   {
     "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:

   Shell

   curl -X POST \
     --location 'https://sandbox.ebanxpay.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.

   JSON

   {
     "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.ebanxpay.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 successfully Cancelled a recurring Pix Automático payment.

   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

Need help?

• Existing merchants: Email sales.engineering@ebanx.com for integration support.
• New to EBANX? Complete the Merchant Signup Form to contact our commercial team.