Cancelling Pix Automático Enrollments

Overview

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

How it works

To cancel an enrollment through EBANX Direct API, please follow the steps below.

1. Make sure that the enrollment status is equal to PENDING or ACCEPTED

   You can only cancel an enrollment if its status is equal to pending or accepted. You can check the status of your payment using the end-point ws/userenrollment/query referencing to its merchant_enrollment_code.

   Check the example:

   curl POST 'https://sandbox.ebanxpay.com/ws/userenrollment/query' \

   --header 'Content-Type: application/json' \

   --data '{

   "integration_key": "{{integration_key}}",

   "enrollment": {

   "merchant_enrollment_code": "{{unique_enrollment_code}}"

   }

   }'

   A successful request will return a JSON response like the one shown below. Enrollments with a status of accepted or pending are eligible for cancellation. Other possible enrollment statuses include not_accepted, expired, not_found, and revoked, none of which can be cancelled

   {

   "status": "SUCCESS",

   "enrollment": {

   "status": "accepted",

   "email": "{{customer_email}}"

   },

   "subscription": {

   "subscription_name": "Descriptor of the subscription.",

   "expiration_date": "2025-12-30",

   "frequency": "monthly",

   "fixed_amount": 19.90,

   "max_amount_floor": null,

   "retry": "allow_3R_7D"

   }

   }

2. Cancel the enrollment using /ws/userenrollment/pix-automatico

   To cancel an enrollment, you just need to call the end-point /ws/userenrollment/pix-automatico (from your server) with the following required fields:

   Parameter	Requirement	Description
   integration_key	Required	Your unique and secret integration key
   payment_type_code	Required	Must be pix-automatico
   operation	Required	Must be cancel

   Enrollment data:

   Parameter	Requirement	Description
   country	Required	Must be BR
   email	Required	Customer e-mail
   merchant_enrollment_code	Required	The unique enrollment identifier

   Please, check the example below:

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

   --data '{

   "integration_key": "{{integration_key}}",

   "payment_type_code": "pix-automatico",

   "operation": "cancel",

   "enrollment": {

   "country": "BR",

   "email": "{{customer_email}}",

   "merchant_enrollment_code": "{{merchant_enrollment_code}}"

   }

   }'

   A successful request will return a JSON response similar to the one below, with a status revoked.

   {

   "status": "SUCCESS",

   "enrollment": {

   "status": "revoked"

   }

   }

3. Handling Scheduled Payments

   

   When an enrollment is cancelled, any scheduled payment will also be cancelled, unless the payment is set for the following day and the cancellation request is made after 10 PM BRT.

   Important

   According to the payment method rules established by the Brazilian Central Bank, if an enrollment is cancelled between 10:00 PM BRT and 11:59 PM BRT, payments scheduled for the following day will still be processed as usual.

   As soon as the payment is canceled by the customer's bank, the payment status is modified from PE to CA and a Status Update notification is sent.

   {

   "operation":"payment_status_change",

   "notification_type":"update",

   "merchant_payment_code":"{{unique_payment_code}}"

   }

   Referencing the payment hash, use the ws/query endpoint to get the latest status of the payment.

   Check the example:

   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 CA for the successful recurring payment.

   {

   "payment": {

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

   "country": "BR",

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

   "merchant_enrollment_code": "{{unique_enrollment_code}}",

   "status": "CA",

   "status_date": "2024-01-18 03:00: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",

   "payment_type_code": "pix-automatico",

   "pre_approved": false

   },

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