Recurring Payment Retries
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.
*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
retriesnode 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 thews/queryendpoint 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
PEfor the retriable recurring payment, along with the remaining retry attempts inavailable_retries.{
"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": {
"merchant_enrollment_code": "{{unique_enrollment_code}}",
},
},
"status": "SUCCESS",
"retries": {
"available_retries": 3,
"payment_attempts": [
{
"attempted_at": "2024-01-17 21:11:35",
"attempt_response": "Insufficient funds or limit restrictions in the user's account"
}
]
}
}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 thews/retryendpoint 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}}",
"status": "PE",
"status_date": "2024-01-17 23:13:47",
"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": {
"merchant_enrollment_code": "{{unique_enrollment_code}}",
},
},
"status": "SUCCESS",
"retries": {
"available_retries": 2,
"payment_attempts": [
{
"attempted_at": "2024-01-17 21:11:35",
"attempt_response": "Insufficient funds or limit restrictions in the user's account"
},
{
"attempted_at": "2024-01-18 00:00:00",
"attempt_response": null
}
]
}
}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
PEtoCOand a Status Update notification is sent.{
"operation":"payment_status_change",
"notification_type":"update",
"merchant_payment_code":"{{unique_payment_code}}"
}Referencing the payment
hash, use thews/queryendpoint 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
COfor 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,
"enrollment": {
"merchant_enrollment_code": "{{unique_enrollment_code}}",
},
},
"status": "SUCCESS",
"retries": {
"available_retries": 2,
"payment_attempts": [
{
"attempted_at": "2024-01-17 18:11:35",
"attempt_response": "Insufficient funds or limit restrictions in the user's account"
},
{
"attempted_at": "2024-01-18 08:00:00",
"attempt_response": "Payment successful"
}
]
}
}Congratulations!
You have succesfully Retried a Pix Automático Recurring Payment.
For more information, refer to theDirect API reference guidechevron_right
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.