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.
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
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 adds the
available_retriesfield 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 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}}",
"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"
}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.
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}}",
"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"
}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}}",
"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"
}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.