Error Scenarios

Overview

In the previous sections of this documentation, you explored the happy path for enrollment creation, payment scheduling, and payment retries. Naturally, potential errors may arise. By reviewing this guide, you will gain insight into the unhappy paths and learn how to address any issues effectively.

Errors in the Enrollment Creation

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:

Response Code	Error Message	Description
BP-UE-03	Field %field_name% is required for pix-automatico	The field mentioned on the message on %field_name% placement is required and can not be null in an enrollment creation
BP-UE-06	Field enrollment.country must be a valid country abbreviation	This field is required and can not be null in an enrollment creation
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 filled with "pix-automatico" and the field country must be "BR˜
BP-UE-10	Payment type not enabled in full mode for merchant	Pix Automatico 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_codemust be a unique enrollment identification. You can't repeat it
BP-UE-23	Field enrollment.subscription.frequency is Required	This field is required and can not be null in an enrollment creation. Available frequencies are: weekly,monthly, quarterly,semi-annual,annual
BP-UE-24	Field enrollment.subscription.start_date must be a future date	The start_date is the day when the payment that initiates the subscription will be charged, thus it can't be in the past

Errors in the Payment Schedule

After your customer authorized the enrollmrnt creation, scheduling a recurring payment is pretty simple and you can do it through our EBANX Direct API.

To make sure you will have a successful payment, avoid the errors below:

Response Code	Error Message	Description
BP-DR-57	Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyy	Expected billing date must follow the format DD/MM/YYYY
BP-DR-58	Invalid due_date for pix-automatico: max interval 10 days	Expected billing date (DD/MM/YYYY) must be between 2 and 10 days after the current date
BP-DR-59	Invalid due_date for pix-automatico: min interval 2 days	Expected billing date (DD/MM/YYYY) must be between 2 and 10 days after the current date
BP-DR-60	Max one payment per cycle	There is a maximum of one payment shcheduled in each cycle. The cycle starts on the start_dateand renews depending on the frequencyset in the enrollment creation
BP-DR-182	Enrollment is not accepted, Cannot transact	This error happens because the status of the enrollment is not accepted. It is only possible to create payments for active enrollments

Errors in the Payment Retry

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:

Response 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