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.

Availability

Pix Automático integration through Direct API will be available in Brazil only.

What you will need

A Sandbox Account

As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.

Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!

Sign up for an EBANX Sandbox Account here

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 SUCCESS

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

2. Cancel the enrollment using /ws/userenrollment/cancel end-point

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

   Field	Description
   integration_key	Your unique and secret integration key
   merchant_enrollment_code	The unique enrollment identifier

   Please, check the example below:

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

   -d 'integration_key={{integration_key}}' \

   -d 'merchant_enrollment_code={{unique_enrolment_code}}' \

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

   {

   "status": "CANCELED",

   "payment_type_code": "pix-automatico",

   "enrollment": {

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

   "country": "BR",

   "currency_code": "BRL",

   "back_urls": {

   "success": "{{success_url}}",

   "failure": "{{failure_url}}"

   },

   "subscription": {

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

   "first_payment_date": "2024-01-17",

   "expiration_date": "2024-07-03",

   "frequency": "weekly",

   "amount": 19.90,

   "retries": true

   },

   "customer": {

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

   "document": "{{customer_document}}"

   },

   "pix":{

   "credit_allowed": true //true by default if not informed.

   },

   "qr_code_value": "00020101021226740014br.gov.bcb.pix2552pix.ebanx.com\/qr\/v2\/F2D9448AA5B94ED3450A4A8933748F5952040000556345643602BR5911Ebanx LTDA.6008CURITIBA62070503***63045022"

   }

   }

3. Handling Scheduled Payments

   Important

   If an enrollment is canceled between 10:00 PM BRT and 11:59 PM BRT, payments scheduled for the following day will still be processed normally. If all payments must be canceled, the enrollment cancelation request must be sent before 10:00 PM BRT

   

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

   }

   Using the ID provided in merchant_payment_code, use the ws/query endpoint to get the latest status of the payment.

   Check the example:

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

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

   --data '{

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

   "merchant_payment_code": "{{unique_payment_code}}"

   }'

   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-16 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 goes live on June 16th 2025. Stay tuned for Sandbox Environment availability on December 1st 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.