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 in the user's account	The user account has insufficient balance for the transaction at this moment. Please try later.
ENROLLMENT_CANCELLED	Enrollment is not in active state	The enrollment has been cancelled by the user
LIMIT_EXCEEDED	Limit restrictions in the user's account.	This can be due to breach in number of attempts allowed as per remitter's bank.
TIMEOUT_NPCI_UNAVAILABLE	External service not available, try again	We received a network unavailable momentarily. Please try later.
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. Please try later.
USER_ACCOUNT_CLOSED	User account is closed or blocked	The user's bank account is either closed or has a debit freeze. Please request user to try with a different vpa/account.
DUPLICATE_TRANSACTION	Duplicate Mandate/transaction request	Expected when a request for the same mandate/txn has been made twice.
MANDATE_PAUSED	Enrollment paused by the customer	The enrollment has been paused by the user.
MANDATE_EXPIRED	Enrollment has expired	Expected when the enrollment expiry date has been breached .
INVALID_AMOUNT	Value sent in the amount field is incorrect	Expected when the amount field value is incorrect. Please revalidate the amount before retrying.
MAX_AMOUNT_EXCEEDED	Mandate amount as set by bank exceeded	This can be due to breach in per transaction limit or per day limits defined at remitter's bank.
PAYEE_BLOCKED_AT_REMITTER	Merchant blocked at Remitter Bank due to internal checks	Merchant has been blocked at remitter bank due to their internal fraud or risk checks.
INVALID_VPA	VPA is either invalid or is inactive	The VPA used for this transaction is not active or present. Please ask user to try with a valid & active VPA.
NOTIFICATION_NOT_FOUND	Pre-debit notification not sent for the payment	Here, the PDN was not sent or not delivered successfully to the user for this payment. Please retry the PDN and payment cycle again.
MANDATE_REVOKED	Enrollment revoked by the customer	The enrollment has been revoked by the user.
MANDATE_NOT_FOUND	Enrollment does not exist or is not valid in the network/issuer system	Here, the enrollment ID is either not present or is invalid in network or issuer systems. Please initiate new enrollment for such scenarios.
NO_ACTION_BY_PAYER	Authentication not completed by user	This error is received when user fails to complete authentication before request expiry.
INVALID_PARAM	Parameter is invalid	One of the parameters such as currency, etc. is invalid. Please recheck before retrying.
REMITTER_BANK_NOT_AVAILABLE	Bank doesn't support the payment method	Remitter bank is either not live or doesn't support the payment method.
SUSPECTED_FRAUD_REMITTER_BANK	Fraudulent transaction as per bank system	Remitter bank has declined due to internal risk checks.
INVALID_MPIN_OR_OTP	Authentication failed due to incorrect input by user	The user failed to validate the request correctly.
CUSTOMER_NUMBER_OR_ACCOUNT_CHANGE	User account has undergone changes to primary values	If the user's bank account or number is changed, the payment will fail. Please request user to try with a different VPA/account.
INVALID_AMOUNT	Value sent in the amount field is incorrect	Expected when the amount field value is incorrect. Please revalidate the amount before retrying.
TIMEOUT_BENEFICIARY_BANK_UNAVAILABLE	External service not available, try again	The bank was unavailable and did not respond to our payment scheduling attempt. Please try later.
TIMEOUT_ACQUIRING_BANK_UNAVAILABLE	External service not available, try again	The bank was unavailable and did not respond to our payment scheduling attempt. Please try later.
DO_NOT_HONOUR	Payment rejected by bank due to internal checks	Bank has declined to process the transaction due to internal checks.
ATTEMPTS_EXCEEDED_MPIN_OR_OTP	Authentication failed due to incorrect input by user	The user failed to validate the request correctly within the allowed attempts.
CANCELED_BY_PAYER	User has declined the` transaction	This error is received when user proactively declines or rejects the payment.
TECHNICAL_ERROR	Technical failures or gateway errors	Here, the payment failed due to gateway level errors. Please try later.
BP-DR-86	Parameter is invalid	The parameter sent was not valid. You would receive this in sync.
BP-REF-15	Invalid operation: X	You are trying an invalid operation. You would receive this in sync response.
DEFAULT_ERROR	Unknown error	You will receive this when an unexpected error is received from the network .

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.