Payment

An overview of all related Payment errors on the client and server-side

56045604

Introduction

We use standard HTTP response codes for success and failure notifications. In general, 200 HTTP codes correspond to success, 40X codes are for a developer or user-related failures, and 50X codes are for Okra-related issues. We’re always working to minimize payment errors related to Okra integrations when initiating payments 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 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 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 24 hours transaction limit has been exceeded.

Troubleshooting steps

  • Try again in the next 24 hours
{
      type: 'error',
      error: true,
      status: false,
      code: 1051,
      method: 'Limit - Exceeded account limit',
      message: msg || 'Customer has exceeded their daily transfer limit, please try again in 24 hours'
    }

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](https://docs.okra.ng/reference/initiatepayment) 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: msg || '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: msg || '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_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', 
      id
    }

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
    }

Did this page help you?