Error Scenarios
This guide outlines potential errors that may occur during enrollment creation, payment scheduling, payment processing, and payment retries.
Pix Automático operates in partnership with users' banks through the Brazilian Central Bank's environment. As such, there are synchronous error scenarios triggered by EBANX, in accordance with the Central Bank's guidelines. These are identified by error codes starting with "BP", such as "BP-UE-03" or "BP-DR-57".
Additionally, there are asynchronous errors that may originate from the user's bank, often related to account status or operational issues. Both types of errors are listed below.
Enrollment Csreation errors
As detailed in the Variable Enrollments and Fixed Enrollments sections, you can create a new enrollment by calling the ws/userenrollment API, or the ws/direct API if the enrollment is accompanied by an instant payment.
If your enrollment creation is unsuccessful, you may encounter the following errors:
| Code | Error Message | Description |
|---|---|---|
| BP-UE-03 | Field %field_name% is required for pix-automatico | The field mentioned in %field_name% is required and cannot be left null during enrollment creation. |
| BP-UE-06 | Field enrollment.country must be a valid country abbreviation | This field is mandatory and cannot be null during enrollment creation. It must contain a valid country abbreviation. |
| BP-UE-07 | Field payment_type_code is required | The field must be filled with "pix-automatico". |
| BP-UE-08 | Field payment_type_code must be valid | The field must be filled with "pix-automatico". |
| BP-UE-09 | The given payment_type_code is not enabled for this country | The field payment_type_code must be "pix-automatico" and country must be "BR". |
| BP-UE-10 | Payment type not enabled in full mode for merchant | Pix Automático payment type must be enabled in your EBANX Dashboard. |
| BP-UE-16 | This enrollment code already exists, please generate another enrollment code for the customer | merchant_enrollment_code must be unique. You cannot reuse the same enrollment code. |
| BP-UE-23 | Field enrollment.subscription.frequency is required | This field is required and cannot be left null during enrollment creation. Available frequencies: weekly, monthly, quarterly, semi-annual, annual. |
| BP-UE-24 | Field enrollment.subscription.start_date must be a future date | The start_date must be a future date, as it marks when the first payment in the subscription will be charged. It cannot be in the past. |
Payment Scheduling errors
After your customer authorizes the enrollment creation, scheduling a recurring payment is straightforward and can be done through the EBANX Direct API.
If a payment scheduling attempt fails, you can review the error details and try again, if applicable.
To increase your chances of a successful payment, avoid the errors listed below. These scenarios are returned synchronously by EBANX in the response to your payment request, meaning the payment will not be created.
| Code | Error Message | Description |
|---|---|---|
| BP-DR-57 | Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyy | The expected billing date must follow the format DD/MM/YYYY. |
| BP-DR-58 | Invalid due_date for pix-automatico: max interval 10 days | The expected billing date must be between 2 and 10 days after the current date (DD/MM/YYYY). |
| BP-DR-59 | Invalid due_date for pix-automatico: min interval 2 days | The expected billing date must be between 2 and 10 days after the current date (DD/MM/YYYY). |
| BP-DR-60 | Max one payment per cycle | Only one payment can be scheduled per cycle. The cycle starts on the start_date and repeats based on the frequency defined during enrollment. |
| BP-DR-182 | Enrollment is not accepted, Cannot transact | This error occurs if the enrollment status is not accepted. Payments can only be created for active enrollments. |
There are other failure scenarios of validations that occur on payer bank enviroment and are returned to you assyncronously. Your customer's bank has up to two hours to either confirm or reject a payment scheduling attempt.
For the cases below, you will receive a payment status notification. The payment that was PE(pending), will be cancelled and turn into CA. On the query, you will be able to check the reason in the field payment.decline_reason.
| Decline Reason | Description |
|---|---|
| Payment declined as the amount exceeds the maximum threshold defined by the payer. | For each enrollment, the customer can set a maximum amount for recurring payments and can update it over time. This limit cannot be lower than the max_amount_floor defined by the merchant during enrollment creation. Neither the merchant nor EBANX will have visibility into the exact amount chosen by the customer or any updates. We will only know if a payment was rejected due to reaching this limit. |
| User account is closed | If the user's bank account is closed and they can no longer make transactions, the payment will fail. In most cases, the enrollment will be canceled shortly after the account is closed. |
| External service not available, try again | The user's bank was unavailable and did not respond to our payment scheduling attempt. |
Payment Processing errors
At this point, you have scheduled the payment and its status is PE. It will be processed by the customer's bank on the due_date set in the request.
If a payment attempt fails, EBANX will send a notification to inform you of the failure. There are three possible failure scenarios for Pix Automático:
- Insufficient funds in the customer’s enrolled account (no available balance).
- Insufficient Pix Automático limit: The customer has set a daily transaction limit that was exceeded.
- Operational failure: An issue occurred within the bank system.
However, the specific reason for the failure is not disclosed by the customer's bank.
Due to data protection regulations, the Central Bank has defined strict communication rules that prevent detailed responses. As a result, when you query a payment, you will only receive a generic attempt_response: Payment failed due to insufficient funds or limit restrictions in the user's account
The same applies to retry attempts, which are listed under the payment_attempts node in the query response. If a retry fails, it will also include an attempt_response.
What happens on the customer Bank system and UX:
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.
Payment Retry errors
Payment retries for Pix Automatico have strict rules that at this point you have already known: It is possible to request up to three retries within a seven-day window, with a maximum of one retry per day.
If one of this rules is violated, you may see the errors below:
| Code | Error Message | Description |
|---|---|---|
| BP-R-3 | Payment is not pending | Payments that are already confirmed (CO) or were cancelled (CA) can not be retried, only pending (PE) payments are allowed to be retried. |
| BP-R-4 | Payment is not eligible for retry | In the enrollment creation, the retry policy was configured to disallow retries, or the 7-day retry window has passed, making retries no longer possible |
| BP-R-5 | Payment was retried today | There is a maximum of one retry per day |
| BP-R-6 | Payment has no available retries | The maximum of three retries was reached |
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.