Recurring Payment Retries

Overview

In the event of a failed payment attempt, EBANX will send a notification to inform you of the failure.

There are only three possible payment failure scenarios for Pix Automático:

  • Insufficient funds in the customer’s enrolled account: The account has no balance.
  • Insufficient available limit for Pix Automático: Customers can set a limit for daily Pix Automático transactions.
  • Operational failure: Issues originating from the instant payments system.

If you configured the retry policy during enrollment creation as allow_3R_7D, the payment status will remain pending (PE). According to the standards of this payment method, you can request up to three retries within a seven-day window, with a maximum of one retry per day.

By following this integration guide, you will learn how to effectively retry failed recurring payments.

How it works

To complete an Pix Automático retry, please follow the steps below.

  1. EBANX notifies payment failure and retry availability

    Your title

    Once the customer's bank notifies EBANX that the payment has failed, EBANX adds the available_retries field to the payment, specifying how many retry attempts there are left and sends a notification.

    {
    "operation":"payment_status_change",
    "notification_type":"update",
    "merchant_payment_code":"{{unique_payment_code}}"
    }

    Using the payment hash, call 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 PE for the retriable recurring payment, along with the remaining retry attempts in available_retries.

    {
    "payment": {
    "hash": "{{unique_payment_hash}}",
    "country": "BR",
    "merchant_payment_code": "{{unique_payment_code}}",
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "status": "PE",
    "available_retries": 3,
    "status_date": "2024-01-17 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"
    }

  2. Call the /ws/retry API to schedule the Pix Automático payment retry

    Very Important!

    Payments can be retried once a day, up to 3 times, in a 7 day period after notification. After 3 unsuccessful retry attempts or 7 days past with no confirmation, the payment will be automatically canceled.

    Your title

    Using the payment hash, from the previous step, use the ws/retry endpoint to schedule.

    Check the example:

    curl POST 'https://sandbox.ebanxpay.com/ws/retry' \
    --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. The payment retry also operates in a schedule logic and will not be confirmed immediately.
    On the retry response, Pix Automático payment will still have a pending (PE) status and the available retries will decrease.

    {
    "payment": {
    "hash": "{{unique_payment_hash}}",
    "country": "BR",
    "merchant_payment_code": "{{unique_payment_code}}",
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "status": "PE",
    "available_retries": 2,
    "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"
    }

  3. Confirming the Payment after a Retry

    Your title

    As soon as the payment retry is confirmed by the customer's bank, the payment status is modified from PE to CO 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 CO 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": "CO",
    "status_date": "2024-01-18 03:00:00",
    "open_date": "2024-01-10 13:00:00",
    "confirm_date": "2024-01-17 03:00:00",
    "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?

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