OPay Error Codes

When a payment fails, it can be useful to retrieve the error code returned by the customer’s bank, the payment network or the payment processor. Such error codes can be used to determine the potential cause of the failure, and give valuable insights to your customer success teams.



(in test mode only) If you want to trigger a specific error when integrating with OPay, simply enter a desired error code as the transaction amount.


OPay uses HTTP response status codes to indicate the success or failure of your requests. If your request fails, OPay returns an error using the appropriate status code. On this page, you will find a complete list of all potential error codes with an explanation of the specific reason the error occurred.

Error codes are normalized by OPay to provide a convenient and general error mapping. OPay aims to return all the available information, while acquirer banks sometimes simply return generic error codes instead of detailed error information.



Note that this page does not reflect all possible error codes returned by OPay APIs or SDKs. New codes are added on a daily basis and depend on banking partners and issuing banks. It is highly recommended to handle cases where the returned error code isn’t known by your application as payment declines.

Codes are split in two distinct categories:

  1. OPay Error Codes - represent possible errors that are returned by OPay APIs and/or SDKs
  2. Acquirer Bank Error Codes - represent possible errors returned by the processing bank.

OPay Error Codes

Represent possible errors that are returned by OPay APIs and/or SDKs

09 time out
90 system failure
91 refund error, please try again later
96 search order error, please try again later
97 create checkout session failed
98 Invalid request header with requestId
99 request channel parameters are not valid

Acquirer Bank Error Codes

Possible transaction errors returned by the processing bank

05 Do not honour
13 Invalid Amount
51 Insufficient funds
54 Expired card
57 Transaction not permitted to cardholder
62 Restricted card

Keep Customers Informed

As you can see, there are different reasons for failed transactions. Therefore, you should know what the various codes mean in order to explain it accurately to your customers. In the process of making a payment, a customer can encounter issues with their card. They can either try a different payment method, discontinue their purchase, choose a different online store (24% of online customers) or contact you directly. Either way, you need to ensure that the customer is kept well informed.

User Profile 12 messages

James Jones
Application Developer
Recent Notifications
Another purpose persuade Due in 2 Days
Would be to people Due in 2 Days
The best product Due in 2 Days