Error Codes

Below is an exhaustive list of all the error codes that you may encounter when interacting with our Payments API, for both Checkouts, Payments and Refunds.

insufficient_funds101

The user has a valid account with the gateway but his funds or his credit limit are below the checkout amount.

wrong_credentials405

The user entered credentials that were not recognized by the gateway. Example: the user entered a phone number and a password, but the gateway is stating the password doesn't match.

user_doesnt_exist404

The user entered an identifier which the gateway deemed not connected to an account, but the credentials were either found or deemed potentially existing. Example: the user entered a valid phone number and the gateway informed us there's no account tied to it.

unexpected_error_from_partner1000

The gateway returned an error that was not documented in their technical docs.

unexpected_technical_error1001

A generic technical error ocurred.

account_locked406

The user account exists but is locked and it requires some form of activation or communication between the user and the gateway.

cancelled202

The transaction was cancelled by the user outside of our UI, e.g. when they receive a code by Orange Money by SMS and answer No.

wrong_tenant_credentials1002

The API keys that you provided for this gateway are not correct

wrong_national_id_format407

The ID or Passport provided by the user has the wrong format

wrong_email_format

The e-mail provided by the user has the wrong format

wrong_phone_format500

The phone # was rejected by the gateway

wrong_card_credentials408

The card details provided are not correct

rejected_by_bank700

The gateway rejected this transaction specifically and did not provide further info

not_found404

Orchestrapay resource not found

rate_limit_exceeded102

The gateway has a rate limiting feature (they throttle our requests) and we've exceeded it

Errors with code unexpected_technical_error and unexpected_error_from_partner are constantly monitored by our team and continuously fixed.

Last Error & Last Step

Because Transaction Intents can fail multiple time throughout their lifecycle, we are using the last error reporting method. If a Transaction Intent fails multiple time but then succeeds, it will not have a last error. Along with the last error, we also provide you the last step that the user did successfully.

Last errors are always the error codes above, whereas last steps are gateway-specific:

Gateway	Workflow Steps
Contact	1. Collect National ID 2. Retrieve Tenors 3. Show Summary 4. Enter OTP
Instapay	1. Authenticate 2. Poll Status
Premium Card	1. Enter Card Details 2. Select Tenure 3. Enter OTP
Opay	1. Redirect to Opay 2. Poll Status
PalmPay	1. Redirect to PalmPay 2. Poll Status
Spotit	1. Enter Phone 2. Choose Bank 3. Poll Status
Souhoola	1. Authorize Payment 2. Pick Downpayment 3. Pick Tenure 4. Show Summary 5. Enter OTP
CredPal	1. Enter BVN & Phone 2. Authenticate
Orange Money	1. Enter Phone 2. Poll Status
Binga / Wafacash	1. Authenticate 2. Poll Status
Diar Dzair	1. Create Transaction 2. Poll Status
Mobile Money Wallet	1. Enter Phone 2. Poll Status
Forsa	1. Enter Phone 2. Select Category 3. Enter OTP
Easybuy	1. Authorize Payment 2. Confirm Order 3. Poll for Status
Paystack Bank Transfer	1. Enter Contact Details 2. Poll Status
Paystack Credit Card	1. Enter Email 2. Redirect 3. Poll Status