Retry Pix Automático Recurring Payment | EBANX Developers Academy

In the event of a failed payment attempt, EBANX will send a notification to inform you of the failure, after 9 PM BRT of the payment the due date*.

There are only three possible payment failure scenarios for Pix Automático, however, the specific reason for the failure is not disclosed by the customer's bank. For the sake of knowledge, these are the potential reasons of a payment processing failure:

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 as allow_3R_7D during enrollment creation, the payment will remain in the PE (pending) status after the original attempt fails, allowing you to proceed with retries in the following days. According to Pix Automático rules, you can submit up to three retries within a seven-day window, limited to one retry per day.

Retries are scheduled for the following day. So, every time you send a request to our retry endpoint and receive a successful response, the payment attempt will be processed on the next day.

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

note

*Why payment failure notification will come only after 9 PM BRT on the due date?

The bank's first attempt window is between 12:00 AM and 8:00 AM BRT. If the attempt fails, the bank notifies users explaining the reason and suggesting actions such as topping up their account or adjusting transaction limits. Customers are expected to take these actions before the intraday retry attempts.

Intraday retry attempts are intiated by the banks and occur a second window, between 6:00 PM and 9:00 PM BRT. Banks can process as many intraday retries as needed, but at least one is mandatory.

If the payment is not confirmed by 9:00 PM BRT, EBANX will consider it unsuccessful and notify merchant. After this notification, you may send a retry request to be processed the next day. The retry you requested will follow the same two-window process as the original payment on the previous day.

Requirements

Retry policy - The enrollment must have retry policy configured as allow_3R_7D

Instructions

Follow the steps below.

Receive payment failure and retry availability from EBANX.

Once the customer's bank notifies EBANX that the payment has failed, EBANX sends a notification and adds the retries node to the payment query response, specifying how many retry attempts there are left and the results of each attempt.

{
   "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.

Also note the retry_status field, it will indicate if the payment is available to be retried. The possible values are:

AVAILABLE: Retries can be requested.
LOCKED: A retry attempt is currently pending and being processed. New attempts cannot be triggered until the current one is completed.
ENDED: The retry window (7 days after the original charge) has expired, or the maximum of 3 retry attempts has been reached. No further retries can be initiated.

{
    "payment": {
        "hash": "{{unique_payment_hash}}",
        "country": "BR",
        "merchant_payment_code": "{{unique_payment_code}}",
        "status": "PE",
        "status_date": "2024-01-17 21:11:36",
        "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,
        "enrollment": {
            "status": "accepted",             
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "retries": {
            "retry_status": "AVAILABLE",
            "available_retries": 3,
            "payment_attempts": [
                {
                    "attempted_at": "2024-01-17 21:11:33",
                    "attempt_response": "INSUFFICIENT_FUNDS_OR_DAILY_LIMIT"
                }
            ]
        }
    },
    "status": "SUCCESS",
}

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

Very Important!

Retries are scheduled for the following day. So, every time you send a request to our retry endpoint and receive a successful response, the payment attempt will be processed on the next day.

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

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 similar to the one below. The payment retry follows a scheduled logic and is not confirmed immediately.

In the retry response, the Pix Automático payment will still have a pending (PE) status, and the number of available retries will decrease.

The retry_status will be LOCKED because a retry is already scheduled for the next day.

Meanwhile, the attempt_response will be PENDING, indicating that the retry has not yet been processed.

{
   "payment": {
       "hash": "{{unique_payment_hash}}",
       "country": "BR",
       "merchant_payment_code": "{{unique_payment_code}}",
       "status": "PE",
       "status_date": "2024-01-17 21:11:36",
       "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,
       "enrollment": {
            "status": "accepted", 
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "retries": {
            "retry_status": "LOCKED",
            "available_retries": 2,
            "payment_attempts": [
                {
                    "attempted_at": "2024-01-17 21:11:33",
                    "attempt_response": "INSUFFICIENT_FUNDS_OR_DAILY_LIMIT"
                },
                {
                    "attempted_at": "2024-01-18 18:35:33",
                    "attempt_response": "PENDING"
                }
            ]
        }
    },
    "status": "SUCCESS",
}

Confirming the Payment after a Retry

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}}",
       "status": "CO",
       "status_date": "2024-01-18 08:00:00",
       "open_date": "2024-01-10 13:00:00",
       "confirm_date": "2024-01-18 08: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,
        "transaction_status": {
          "acquirer": "EBANX IP",
          "code": "OK",
          "description": "Recurring payment successfully paid",
          "description_code": "ACCEPTED"
        },
        "enrollment": {
            "status": "accepted",             
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
        },
        "retries": {
            "retry_status": "ENDED",
            "available_retries": 2,
            "payment_attempts": [
                {
                    "attempted_at": "2024-01-17 21:11:33",
                    "attempt_response": "INSUFFICIENT_FUNDS_OR_DAILY_LIMIT"
                },
                {
                    "attempted_at": "2024-01-18 18:35:33",
                    "attempt_response": "ACCEPTED"
                }
            ]
        }   
    },
    "status": "SUCCESS"
}

note

The attempt_response possible values are:

"PENDING" for payments that are scheduled and have not yet been processed.
"INSUFFICIENT_FUNDS_OR_DAILY_LIMIT" for payment liquidations that were not sucessful, due to insufficient funds or reaching the Pix Automático daily limit.
"ACCEPTED" for payments that were successfully completed.
"FAILED" for attempts that were scheduled but not processed, typically because the payment was canceled (e.g., the user’s account was closed).

Congratulations!
You have succesfully Retried a Pix Automático Recurring Payment.
For more information, refer to the
Direct API reference guide

Product Launch Date

Pix Automático will be available starting June 16, 2025. In the meantime, you can test and explore the features using our Sandbox environment, which has been live since December 1, 2024!

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.

Recurring Payment Retries

Requirements​

Instructions​

Receive payment failure and retry availability from EBANX.

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

Confirming the Payment after a Retry

Congratulations!

Still need help?

Requirements

Instructions