Handling User Driven Cancelations | EBANX Developers Academy

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.

note

Users can cancel a Pix Automático payment only until 00:00 on its due_date. After that, cancellation is no longer possible, and the payment will be processed normally. If it fails, it may also be retried according to the retry policy.

If a payment that the user was unable to cancel in time is processed and confirmed (CO), you can request a Refund to return the funds to the user.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

Instructions

To handle user driven cancellations, follow the steps below.

For user driven cancelled payments

Receive EBANX notification for payment cancellation.

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",
   "hash":"{{unique_payment_hash}}"
}

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

Check the example:

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 CA for the recurring payment and the details of the cancellation inside the transaction_status node.

{
    "payment": {
        "hash": "6834b47584a89429eda5c9272f741c54ce0f6c5921caaaa",
        "country": "br",
        "merchant_payment_code": "1748284533",
        "order_number": null,
        "status": "CA",
        "status_date": "2025-05-27 21:35:33",
        "open_date": "2025-05-26 18:35:33",
        "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": "2025-05-28",
        "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 user",
            "description_code": "CANCELED_BY_PAYER",
        },
        "enrollment": {
            "status": "accepted",  
            "merchant_enrollment_code": "123456789"
        },
        "subscription": {
            "subscription_name": "Descriptor of the subscription", 
            "start_date": "2024-01-01",
            "expiration_date": "2025-12-30", 
            "frequency": "monthly", 
            "retry": "allow_3R_7D",
            "fixed_amount": 19.90
        }, 
        "retries": {
            "retry_status": "ENDED",
            "available_retries": 0,
            "payment_attempts": [
                {
                    "attempted_at": "2025-05-28 18:35:33",
                    "attempt_response": "FAILED"
                }
            ]
        }
    },
    "status": "SUCCESS"
}

Congratulations!
You have succesfully integrated user driven cancelled payments.
For more information, refer to the
Direct API reference guide

For user driven cancelled enrollments

EBANX notifies enrollment cancellation

As soon as the enrollment is canceled by the customer's bank a Status Update notification is sent to the URL defined in your merchant configuration.

{
   "operation":"enrollment_status_change",
   "notification_type":"update",
   "merchant_enrollment_code":"{{unique_enrollment_code}}"
}

Using the ID provided in merchant_enrollment_code, use the /ws/userenrollments/query endpoint to get the latest status of the enrollment.

Check the example:

curl -X POST 'https://sandbox.ebanx.com/ws/userenrollments/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 below, with a status revoked f for the enrollment cancelled by the customer.

{
    "status": "SUCCESS",
    "enrollment": {
        "status": "revoked",
        "email": "{{customer_email}}"
    },
    "subscription": {
        "subscription_name": "Descriptor of the subscription.",
        "start_date": "2024-01-01",
        "expiration_date": "2025-12-30",
        "frequency": "monthly",
        "fixed_amount": 19.90,
        "retry": "allow_3R_7D"
    }
}

EBANX notifies payment cancelation
When an enrollment is cancelled, any payments scheduled for the upcoming cycle will also be cancelled. EBANX will send you a status notification; to review it, follow the steps in the section For Canceled Payments
Congratulations!
You have succesfully integrated user driven cancelled enrollments.
For more information, refer to the
Direct API reference guide

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.

Handling User Driven Cancellations

Requirements​

Instructions​

For user driven cancelled payments​