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

  1. EBANX notifies payment cancelation

    Your title

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

  1. EBANX notifies enrollment cancelation

    Your title

    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/userenrollment/query endpoint to get the latest status of the enrollment.

    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 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.",
    "expiration_date": "2025-12-30",
    "frequency": "monthly",
    "fixed_amount": 19.90,
    "max_amount_floor": null,
    "retry": "allow_3R_7D"
    }
    }

  2. EBANX notifies payment cancelation

    Your title

    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

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?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options:

Edit this page
Last updated on by Sarah Nicolau
On This Page