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-06" 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 Creation 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-12	Unexpected error	Generic error for non-mapped issues.
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, halfyearly, yearly.
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.
BP-UE-26	Field enrollment.subscription.retry must be a valid retry value	The retry field must contain a valid retry strategy value when provided during enrollment creation.
BP-UE-27	Field enrollment.subscription.subscription_name is required	The subscription_name field is required and cannot be left empty during enrollment creation.
BP-UE-30	The field subscription_name size must be between 1 and 35 characters	The subscription_name field must contain between 1 and 35 characters during enrollment creation.

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.

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-9	Parameter due_date is missing or invalid for pix-automatico	Pix Automático payments must include a due date. This due date must fall within 2 to 10 days from the current date.
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	Invalid merchant_enrollment_code for pix-automatico	Payments can only be created with reference to an existing and active enrollment.
BP-DR-61	Subscription Cycle error: This cycle already have one payment	Only one payment can be scheduled per cycle.
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 related to validations that occur within the payer's bank environment and are returned to you asynchronously. The customer's bank has up to two hours to either confirm or reject a payment scheduling attempt.

In case of a scheduling rejection, you will receive a payment status notification. The payment, initially marked as PE (pending), will be canceled and updated to CA. To better understand the cancellation reasons, refer to the Cancellation Reason section.

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: INSUFFICIENT_FUNDS_OR_DAILY_LIMIT .

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.

note

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 initiated 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 these rules are 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) cannot 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

Cancellation Reason

Pix Automático recurring payments follow a scheduling framework; as a consequence, they can be canceled at multiple stages of the payment journey:

• Payment scheduling rejected: if your payment request is not hard-declined (BP-DRs) by our business rules, we will send it to the customer's bank and attempt to schedule it. However, the bank may still reject the scheduling attempt.
• Payment scheduling cancellation: In this case, the scheduling was successfully accepted by the customer’s bank but was later canceled—either proactively by the user or by the merchant, who may cancel the individual payment or the entire enrollment.
• Payment processing failure: If the enrollment policy does not allow retries, the payment will move to CA status right after the first failed attempt. If retries are allowed, the payment will only be canceled (CA) after a maximum of 3 retries or once the 7-day retry window expires.

All of these reasons are included in the transaction_status node of the payment query response. In that section, you’ll find both the description and the description_code that indicate the reason for the cancellation. See the example below:

"transaction_status": {
    "acquirer": "EBANX IP",
    "code": "NOK",
    "description": "Payment declined as the amount exceeds the maximum threshold defined by the payer.",
    "description_code": "MAX_AMOUNT_EXCEEDED"
}

Below you can find the possible description_code values, along with the specific payment step where they may occur and additional details to help you understand the reasons behind each cancellation:

description_code	payment step	details
MAX_AMOUNT_EXCEEDED	Payment scheduling rejected by the bank	For each enrollment, the customer can define a maximum amount for recurring payments, which can be updated over time. This amount cannot be lower than the max_amount_floor set by the merchant during enrollment. Neither the merchant nor EBANX has visibility into the exact amount set or updated by the customer.
USER_ACCOUNT_CLOSED	Payment scheduling rejected by the bank	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 afterward.
TIMEOUT	Payment scheduling rejected by the bank	The user's bank was unavailable and did not respond to our payment scheduling attempt.
CANCELED_BY_PAYER	Payment successfully scheduled but canceled before the due_date	The payment was canceled at the user's request.
CANCELED_BY_MERCHANT	Payment successfully scheduled but canceled before the due_date	The payment was canceled at the merchant's request.
ENROLLMENT_CANCELLED	Payment successfully scheduled but canceled before the due_date	The enrollment was canceled by the user or the merchant, and the associated payments were also canceled.
EXPIRED_AFTER_7DAYS	Payment successfully scheduled but liquidation couldn't be completed	The payment expired after reaching the 7-day cap.
EXPIRED_AFTER_3RETRIES	Payment successfully scheduled but liquidation couldn't be completed	The payment was canceled after three unsuccessful retry attempts.
INSUFFICIENT_FUNDS_OR_DAILY_LIMIT	Payment successfully scheduled but liquidation couldn't be completed	Insufficient funds or daily limit restrictions in the user's account. This failure reason only applies to payments from enrollments that do not allow retries.

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.