Payment Errors

An overview of all Payments product errors that you might encounter on the client and server-side.

Introduction

Okra uses standard HTTP response codes for success and failure notifications. In general, the 200 HTTP code correspond to success, 40X codes are for a developer or user-related failures, and 50X codes are for service-related issues. The team is continuously working to minimize payment errors when payments are initiated and to address connectivity issues across bank infrastructure.

Breakdown of an Okra error

Name	Description
`status`	The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
`message`	A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
`data`	Response data from the API, including the details of the successful or failed response.
`Method`	The method that performs the error function
`code`	The particular error code
`type`	A broad categorization of the error. Safe for programmatic use. Possible values: `SUSPENDED`, `EMPTY_QUEUE`, `FLAGGED_USER`, `NO_RECORD_ID`, `RATE_LIMIT`

DEBIT_RECURRING_API

Common Causes

No consent to initiate recurring debit

Troubleshooting steps

Upgrade your plan to initiate recurring debit
Contact developer support

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1027,
  "method": "Reccuring Auth Error - Payment",
  "message": "Customer has not consented to recurring payments. Please authorize the user for recurring payments to continune."
}

DEBIT_INVALIDACCOUNT

Common Causes

The account provided for payment those not exist
The account provided for payment is incorrect.

Troubleshooting steps

Check the account number and try again
Contact support team, if the issue persists

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1024,
  "method": "Invalid Account - Payments",
  "message": "You are attempting to fund an account that is invalid or no longer exists. Contact the sender or try again."
}

DEBIT_UNCONNECTEDACCOUNT

Common Causes

The account provided for payment those not exist
The account number provided is not connected to your company.

Troubleshooting steps

Check the account number and try again
Connect an account in your dashboard
Contact support team, if the issue persists

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1025,
  "method": "Invalid Account - Connect valid accunt to continue",
  "message": "You are attempting to fund an account that is not connected to your company. Please connect an account via the dash to continue."
}

DEBIT_UNKNOWN

Common Causes

The debit amount value when calling the debit endpoint was too high.
Too many payments were created in a short period of time.
The server time out exceeded

Troubleshooting steps

Shut down your local server and re-run it.
Try again with a smaller amount value
Contact developer support

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1026,
  "method": "Unknown Error - Payments",
  "message": "There was an issue creating a debit for your account. Please try again later."
}

DEBIT_INSUFFICIENT_FUNDS

Common Causes

The debit amount value when calling the debit endpoint was higher than the available funds in the account.

Troubleshooting steps

Try again with a lower amount value.

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1015,
  "method": "Insufficient Funds - Payments",
  "message": "There are insufficient funds in this account to make this debit."
}

DEBIT_API

Common Causes

Invalid token during the authentication process
Account not verified

Troubleshooting steps

Verify your account
Check your login details before login
Contact developer support

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1027,
  "method": "Initial Auth Error - Payment",
  "message": "Customer has not completed their initial authorization. Please authorize the user for payments before trying again."
}

DEBIT_PROFILE

Common Causes

The user provided an Incorrect PIN, OTP, and Card Number
The internet banking or mobile banking details provided by the user is not accepted by the bank

Troubleshooting steps

The user should check the internet banking details provided
The user needs to provide a valid transaction pin, correct OTP or card number
Contact developer support, if the issue persists

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1028,
  "method": "Profile Error - Payment",
  "message": "error message"
}

OTPDEBIT

Common Cause

The user Incorrect provided an incorrect one-time password(OTP)
The user selected an MFA device that is not active.
The institution failed to send the one-time password(OTP) for the user's selected device.

Troubleshooting steps

Input the correct OTP sent to you
Use a hardware/software token if you didn't get an OTP
Contact developer support, if the issue persists

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1023,
  "method": "OTP Error - Payment",
  "message": "You entered an invalid transaction PIN or OTP, please try again."
}

OTPDEBIT_SECRET

Common Cause

Incorrect OTP SECRET provided
The user selected an MFA device that is not active.
The institution failed to send the one-time code for the user's selected device.

Troubleshooting steps

Prompt the user to provide a correct OTP SECRET
The user could use a hardware/software token if an OTP is not sent
Contact developer support, if the issue persists

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1023,
  "method": "OTP Error - Payment",
  "message": "You entered an invalid PIN or Secret, please try again."
}

PAYMENT_INSUFFICIENT_FUNDS

Common Causes

The payment amount value when calling /pay/initiate was too high.

Troubleshooting steps

Try again with a lower payment amount value.

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1050,
  "method": "NSF - Insufficient Funds",
  "message": "Customer did not have sufficient funds to complete this payment"
}

PAYMENT_LIMIT

Common Causes

The daily transaction limit has been reached. Note that this limit is set by the financial institution and not by Okra.

Troubleshooting steps

Try again in the next 24 hours.

{
      "type": "error",
      "error": true,
      "status": false,
      "code": 1051,
      "method": "Limit - Exceeded account limit",
      "message": "Customer has exceeded their daily transfer limit, please try again in 24 hours"
    }

TRANSACTION_LIMIT

Common Causes

Occurs when you reach your transaction limits in your project. Payment transactions initiated through Okra are subject to limits in both number and value. These limits depend on your account traffic and usage.

Troubleshooting steps

Try again when the limits are renewed.
If you want to increase the transaction limits in your project, get in touch via sales@okra.ng.

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 2075,
  "method": "Transaction limit reached",
  "message": "You have exceeded your transaction limits. Please try again when your limits are renewed."
}

PAYMENT_TIMEOUT

Common Causes

The server time-out exceeded

Troubleshooting steps

Shut down your local server and re-run it.
Contact developer support

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1052,
  "method": "Timeout - Server timeout",
  "message": "NIP Timeout issues, please try again"
}

PAYMENT_UNKNOWN

Common Causes

The payment amount value when calling /pay/initiate was too high.
Too many payments were created in a short period of time.
The server time-out exceeded

Troubleshooting steps

Shut down your local server and re-run it.
Contact developer support
Try again with a smaller amount of value.

{
      "type": "error",
      "error": true,
      "status": false,
      "code": 1053,
      "method": "Payment error - Unable to process",
      "message": "Error processing payment, please try again later"
    }

PAYMENT_INVALID_DESC_PAYMENT

Common Causes

The account provided for payments those not exist
The account provided for payment is incorrect.

Troubleshooting steps

Check the account number and try again
Contact the support team, if the issue persists

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 2058,
  "method": "Invalid payment destination",
  "message": "Destination account unavailble at this time. Please try again."
}

PAYMENT_TRY_AGAIN

Common Causes

The server time-out exceeded
Network error

Troubleshooting steps

Shut down your local server and re-run it.
Contact developer support

{
      "type": "error",
      "error": true,
      "status": false,
      "code": 1054,
      "method": "Payment error - try again",
      "message": "Error processing payment, please try again later"
    }

PAYMENT_BOUNCED

Common Causes

The user abandoned the widget before completing the payment.

Troubleshooting steps

Try again and wait till the payment is successful
Check your internet connection
Contact developer support

{
  "type": "error",
  "error": true,
  "status": false,
  "code": 1055,
  "method": "Widget User Bounced",
  "message": "User abandoned widget before completing the payment."
}

PAYMENT_PENDING

Common Causes

Awaiting verification
Too many payments queuing requests

Troubleshooting step

Contact developer support

{
      "type": "payment-pending",
      "error": false,
      "status": true,
      "code": 2056,
      "method": "Payment pending",
      "message": "Payment is pending. Please verify payment to continue",
      "paymentId": "id"
    }

PAYMENT_VALIDATION

Common Cause

NIBSS Instant Payment(NIP) error occurred.

Troubleshooting steps

Check your request body and try again
Contact developer support.

{
      "type": "error",
      "error": true,
      "status": false,
      "code": 2057,
      "method": "Payment authorization",
      "message": "NIP authorization issue. Please try again",
      "paymentId": "id"
    }