Handling User Driven Cancelations
Overview
Pix Automático allows users to manage their enrollments directly through their banking apps. They are able to cancel both enrollments and payments. This guide quickly demonstrates how to handle user driven cancelations 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 handle cancelations performed by the users through EBANX Direct API, please follow the steps below.
For Canceled Payments
EBANX notifies payment cancelation
As soon as the payment is canceled by the customer's bank, the payment status is modified from
PE
toCA
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"}
For Canceled Enrollments
EBANX notifies enrollment cancelation
As soon as the enrollment is canceled by the customer's bank a Status Update notification is sent to the URL defined in Success URL in the enrollment creation.
{"operation":"enrollment_status_change","notification_type":"update","merchant_enrollment_code":"{{unique_enrollment_code}}"}Using the ID provided in
merchant_enrollment_code
, use the ws/userenrollment/query endpoint to get the latest status of the enrollment.Check the example:
curl POST 'https://sandbox.ebanxpay.com/userenrollment/query' \--header 'Content-Type: application/json' \--data '{"integration_key": "{{integration_key}}","merchant_enrollment_code": "{{unique_enrollment_code}}"}'A successful request will return a JSON response like the one below, with a status of
CANCELED
for the enrollment approved by the customer.{"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"}}EBANX notifies payment cancelation
For each pending payment associated with canceled enrollment, follow the steps described in the For Canceled Payments session
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.