Codes

Request Codes

The table below contains the codes returned by the application.

Code

Detail

Description

Possible Resolution

200/201

SUCCESS/CREATED

The transaction was successfully initiated

400

ERROR

The transaction encountered an error

Check Account Balance
Check Payload Currency

401

UNAUTHORIZED

The transaction is unauthorized

Check your credentials (API key)

404

NOT FOUND

The request could not be processed due to invalid input or business rule violation.

Check that all required fields are present.
Check the request URL

500/5xx

SERVER ERROR

The server encountered an error

IP is not whitelisted
Server is down


Example Error Response (400 Bad Request)

If required parameters are missing or invalid, you'll receive a validation error:

[
  {
    "message": "ID cannot be empty or whitespace only"
  },
  {
    "message": "Account code cannot be empty or whitespace only"
  },
  {
    "message": "Account number cannot be empty or whitespace only"
  },
  {
    "message": "ID must be a valid id"
  },
  {
    "message": "Amount must be a number"
  },
  {
    "message": "Amount must be greater than zero"
  },
  {
    "message": "Amount is required"
  },
  {
    "message": "Amount cannot be empty"
  },
  {
    "message": "Reason must be a string"
  },
  {
    "message": "Reason is required"
  },
  {
    "message": "Reason cannot be empty"
  },
  {
    "message": "Reason must be at least 1 character long"
  },
  {
    "message": "Account name must be a string"
  },
  {
    "message": "Account name is required"
  },
  {
    "message": "Account name cannot be empty"
  },
  {
    "message": "Account name must be at least 1 character long"
  },
  {
    "message": "Account number must be a string"
  },
  {
    "message": "Account number is required"
  },
  {
    "message": "Account number cannot be empty"
  },
  {
    "message": "Account number must be at least 1 character long"
  },
  {
    "message": "Currency must be a string"
  },
  {
    "message": "Currency is required"
  },
  {
    "message": "Currency cannot be empty"
  },
  {
    "message": "Currency must be a valid currency code"
  },
  {
    "message": "Network must be a string"
  },
  {
    "message": "Network is required"
  },
  {
    "message": "Network cannot be empty"
  },
  {
    "message": "Network must be at least 1 character long"
  },
  {
    "message": "Metadata must be an object"
  },
  {
    "message": "failureCallbackURL must be a valid string"
  },
  {
    "message": "Reference must be a string"
  },
  {
    "message": "Reference is required"
  },
  {
    "message": "Reference cannot be empty"
  },
  {
    "message": "Reference must be at least 1 character long"
  },
  {
    "message": "Paylink ID must be a valid UUID"
  },
  {
    "message": "Channel must be a string"
  },
  {
    "message": "Email must be a string"
  },
  {
    "message": "Merchant name must be a string"
  },
  {
    "message": "Transaction ID must be a valid id"
  },
  {
    "message": "Transaction ID is required"
  },
  {
    "message": "Transaction ID cannot be empty"
  },
  {
    "message": "OTP must be a string"
  },
  {
    "message": "OTP is required"
  },
  {
    "message": "OTP cannot be empty"
  },
  {
    "message": "OTP must be at least 1 character long"
  },
  {
    "message": "ID must be a valid UUID"
  },
  {
    "message": "Amount must be a valid number"
  },
  {
    "message": "Currency must be one of: <<List of supported currencies>>"
  },
  {
    "message": "Callback URL must be a string"
  },
  {
    "message": "Return URL must be a string"
  },
  {
    "message": "amount must be a valid number"
  },
  {
    "message": "amount is required"
  },
  {
    "message": "amount cannot be empty"
  },
  {
    "message": "amount must be greater than 0"
  },
  {
    "message": "network must be a valid string"
  },
  {
    "message": "network is required"
  },
  {
    "message": "network cannot be empty"
  },
  {
    "message": "accountName must be a valid string"
  },
  {
    "message": "accountName is required"
  },
  {
    "message": "accountName cannot be empty"
  },
  {
    "message": "accountNumber must be a valid string"
  },
  {
    "message": "accountNumber is required"
  },
  {
    "message": "accountNumber cannot be empty"
  },
  {
    "message": "currency must be a valid string"
  },
  {
    "message": "currency is required"
  },
  {
    "message": "currency cannot be empty"
  },
  {
    "message": "recipients must be an array"
  },
  {
    "message": "recipients is required"
  },
  {
    "message": "recipients array cannot be empty"
  },
  {
    "message": "callbackURL must be a valid string"
  },
  {
    "message": "reference must be a valid string"
  },
  {
    "message": "reference is required"
  },
  {
    "message": "reference cannot be empty"
  },
  {
    "message": "Bank must be a string"
  },
  {
    "message": "Bank is required"
  },
  {
    "message": "Bank cannot be empty"
  },
  {
    "message": "Bank must be at least 1 character long"
  },
  {
    "message": "Destination must be a string"
  },
  {
    "message": "Destination must be a valid currency code"
  },
  {
    "message": "Channel must be a valid transaction channel"
  },
  {
    "message": "Sender name must be a string"
  },
  {
    "message": "Sender name is required"
  },
  {
    "message": "Sender name cannot be empty"
  },
  {
    "message": "Sender name must be at least 1 character long"
  },
  {
    "message": "Each recipient must be a valid recipient object"
  },
  {
    "message": "Recipients must be an array"
  },
  {
    "message": "Recipients array is required"
  },
  {
    "message": "Recipients array cannot be empty"
  },
  {
    "message": "Channels must be a string"
  },
  {
    "message": "Date must be at least 1 character long"
  },
  {
    "message": "Email must be a valid email address"
  },
  {
    "message": "Reference cannot be empty or whitespace only"
  },
  {
    "message": "Last name must be a string"
  },
  {
    "message": "Last name is required"
  },
  {
    "message": "Last name cannot be empty"
  },
  {
    "message": "Last name must be at least 1 character long"
  },
  {
    "message": "First name must be a string"
  },
  {
    "message": "First name is required"
  },
  {
    "message": "First name cannot be empty"
  },
  {
    "message": "First name must be at least 1 character long"
  },
  {
    "message": "Phone number must be a string"
  },
  {
    "message": "Phone number is required"
  },
  {
    "message": "Phone number cannot be empty"
  },
  {
    "message": "Phone number must be between 10-15 digits and contain only numbers, +, -, (), or spaces"
  },
  {
    "message": "Currency must be NGN"
  },
  {
    "message": "Virtual account number must be a string"
  },
  {
    "message": "Virtual account number is required"
  },
  {
    "message": "Virtual account number cannot be empty"
  },
  {
    "message": "Virtual account number must be at least 1 character long"
  },
  {
    "message": "Message must be at least 1 character long"
  },
  {
    "message": "Username must be at least 1 character long"
  },
  {
    "message": "Code must be at least 1 character long"
  },
  {
    "message": "Sorry, We can not process this transaction now"
  },
  {
    "message": "Failed to start Workflow"
  },
  {
    "message": "Insufficient wallet balance"
  },
  {
    "message": "accountNumber not allowed in test"
  }
]

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication failed: Invalid api_key"
}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    "currency is required",
    "currency must be one of: GHS, NGN, UGX, XOF, XAF, KES, TZS, ZMW, GBP, EUR, USD, USDC, USDT",
    "currency cannot be empty",
    "currency must be a valid string"
  ]
}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    "accountNumber is required",
    "Account number must be at least 1 character long",
    "accountNumber cannot be empty",
    "accountNumber must be a valid string"
  ]
}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    "network is required",
    "Network must be at least 1 character long",
    "network cannot be empty",
    "network must be a valid string"
  ]
}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    "amount is required",
    "amount must be greater than 0",
    "amount cannot be empty",
    "amount must be a valid number"
  ]
}

//POST is the required HTTP verb, but GET was used resulting in a 404 error.
//Also returned from incorrect url path e.g. POST /disbursements/mobile-money. This hiphernated path is incorrect.
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Cannot GET /disbursements/mobilemoney"
}