Error Scenarios

This guide outlines potential errors that may occur during enrollment creation and recurring payment requests in UPI Autopay operation.

There are synchronous error scenarios triggered by EBANX, in accordance with the product business rules and required fields.

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 Synchronous Errors

As detailed in the Enrollment Creation section, you can create a new enrollment by calling the ws/userenrollment API. If your enrollment creation is unsuccessful, you may encounter the following errors in the response:

EBANX Code	EBANX Message	Details
BP-UE-18	Field enrollment.subscription.expiration_date must be a future date	Incorrect expiration date
BP-UE-03	Field enrollment.email or enrollment.phone_number is required	Mandatory Field is missing
BP-UE-19	Invalid vpa	VPA field has incorrect information
BP-UE-17	Field enrollment.subscription.min/maxamount is Required!	min/max amount is blank
BP-UE-30	The field subscription_name size must be between 1 and 35 characters.	Subscription name character limit
BP-UE-22	enrollment.customer_notify_hash must contain a valid hash.	Notify hash is incorrect
BP-UE-23	Field enrollment.subscription.frequency is Required	Frequency field is blank

Enrollment Creation Asynchronous Errors

EBANX Code	EBANX Message	Details
BP-UE-34	Request with invalid params	The fields are sent with incorrect information
BP-UE-32	Provider internal server error	Partner is facing a downtime
BP-UE-33	Timeout from provider	Request timeout
BP-UE-12	Failed to communicate with provider	API access not enabled (Contact your SE)

Payment Processing Synchronous 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 request 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.

EBANX Code	EBANX Message	Details
BP-DR-86	Parameter is invalid	The parameter sent was not valid.
BP-REF-15	Invalid operation: X	You are trying an invalid operation.
BP-DR-61	Subscription Cycle error: This cycle already have one payment	Only one payment can be requested per cycle. This is not applicable for on-demand enrollments

Payment Asynchronous errors - Cancellation Reason

If your payment request is not hard-declined (BP-DRs) by our business rules, we will send it to the customer's bank. However, the bank may still reject the payment attempt.

In this case, the payment will move to CA (canceled) status and the reason will be 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": {
    "code": "NOK",
    "description": "Insufficient funds or limit restrictions in the user's account",
    "description_code": "INSUFFICIENT_FUNDS"
}

For cancelled payments, the field code will be always NOK(not ok). Below you can find the possible description_code and description values:

description_code	description	Details
INSUFFICIENT_FUNDS	Insufficient funds or limit restrictions in the user's account	User does not have enough balance for the charge.
ENROLLMENT_CANCELLED	Enrollment is no longer active	The payment was canceled at the user's request.
LIMIT_EXCEEDED	Payment declined as the amount exceeds the maximum threshold defined by the payer.	The user has reached the limit set by their issuing bank.
TIMEOUT_NPCI_UNAVAILABLE	External service not available, try again	The user's bank was unavailable and did not respond to our payment scheduling attempt.
TIMEOUT_REMITTER_BANK_UNAVAILABLE	External service not available, try again	The user's bank was unavailable and did not respond to our payment scheduling attempt.
USER_ACCOUNT_CLOSED	User account is closed or blocked	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.

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.