Errors

When a Payaza API request fails, the response body contains a descriptive error message. This page lists all common errors by product area, along with their causes and fixes.

The most common causes of errors are: a missing or incorrectly encoded API key, a reused transaction_reference, or a mismatch between your key’s environment and the X-TenantID header.

Authentication errors

{
  "message": "Authentication failed",
  "status": false,
  "retry_count": 0
}

Cause	Fix
Missing or empty `Authorization` header	Add `Authorization: Payaza <base64-encoded-key>` to every request
API key not Base64-encoded	Encode your key before use — see the Authentication guide
Wrong prefix (e.g. `Bearer` instead of `Payaza`)	Change the prefix to `Payaza`
Test key used with `X-TenantID: live`, or vice versa	Match the key to its environment
Key was regenerated on the dashboard	Copy the new key, re-encode it, and update your integration

Transfer errors

Error message	Cause	Fix
`"Payout amount is less than total credit amount"`	The sum of `credit_amount` values in `payout_beneficiaries` exceeds `payout_amount`	Ensure `payout_amount` equals the sum of all `credit_amount` values
`"Insufficient Balance"`	Your Payaza account balance is below the transfer amount	Top up your account or reduce the transfer amount
`"Invalid transaction pin"`	The `transaction_pin` in the request body is incorrect	Correct the PIN — see how to set your PIN
`"Transaction reference already exists"`	A `transaction_reference` was reused	Generate a unique reference for every transfer attempt
`"Bank code is not correct"`	The `bank_code` value is invalid	Verify the bank code against the supported bank list
`"Account number can only be numbers"`	The `account_number` contains non-numeric characters	Pass only numeric digits
`"Account number must be 10 digits"`	The `account_number` is not 10 digits (NGN only)	Pass a valid 10-digit NUBAN number

Sample responses

{
  "response_code": 500,
  "response_message": "Insufficient Balance"
}

{
  "response_code": 500,
  "response_message": "Invalid transaction pin",
  "response_content": {
    "message": "Invalid transaction Pin",
    "retry_count": 1
  }
}

{
  "response_code": 0,
  "response_message": "Transaction reference already exists. please use unique reference",
  "resp_code": "X03"
}

{
  "response_code": 0,
  "response_message": "Bank code is not correct for reference: payazaTest",
  "resp_code": "X02"
}

See the Transfers guide for the full integration walkthrough.

Virtual Account errors

Error message	Cause	Fix
`"Transaction not found"`	The `transaction_reference` does not exist	Verify you are using the correct reference
`"Reserved Virtual Account does not exist"`	The virtual account number is incorrect or was never created	Check the account number and confirm creation succeeded
`"Could not generate virtual account at the moment"`	Upstream network error	Retry the request. If the issue persists, contact support@payaza.africa

Sample responses

{
  "response_code": 404,
  "response_message": "Transaction not found",
  "response_content": {
    "transaction_reference": ""
  }
}

{
  "response_code": 404,
  "response_message": "Reserved Virtual Account does not exist",
  "response_content": {
    "page": 0,
    "transaction_count": 0,
    "virtual_account_number": "960633617",
    "virtual_account_name": null,
    "virtual_account_status": null,
    "virtual_account_provider_bank": null,
    "transactions": null
  }
}

{
  "response_code": 500,
  "response_message": "Could not generate virtual account at the moment, please try again.",
  "status": "X02"
}

See the Virtual Accounts guide for the full integration walkthrough.

Card errors

Error message	Cause	Fix
`"There is already an authentication outcome associated with the supplied transaction ID"`	Duplicate `transaction_reference`	Generate a new unique reference and retry
`"Unable to determine card payment"`	Invalid or unsupported card details	Verify the card number, expiry date, and CVV
`"Expired card"`	The card’s expiry date has passed	Use a valid non-expired card

Sample responses

{
  "statusOk": false,
  "message": "Transaction Failed",
  "debugMessage": "Value 'TEST1213TEST' is invalid. There is already an authentication outcome associated with the supplied transaction ID. To perform another authentication on the order, provide a new transaction ID.",
  "waitForNotification": false,
  "do3dsAuth": false,
  "paymentCompleted": false,
  "amountPaid": 0,
  "valueAmount": 0
}

{
  "statusOk": false,
  "message": "Transaction Failed",
  "debugMessage": "Value '401200xxxxxx1111' is invalid. Unable to determine card payment.",
  "waitForNotification": false,
  "do3dsAuth": false,
  "paymentCompleted": false,
  "amountPaid": 0,
  "valueAmount": 0
}

{
  "statusOk": false,
  "message": "Transaction Failed",
  "debugMessage": "Expired card",
  "waitForNotification": false,
  "do3dsAuth": false,
  "paymentCompleted": false,
  "amountPaid": 0,
  "valueAmount": 0
}

Use Test Cards to simulate different card outcomes during development.

Account Name Enquiry errors

Error message	Cause	Fix
`"Bank code should be 6 values"`	`bank_code` is not 6 digits	Pass a valid 6-digit bank code as an integer
`"Unknown Bank Code"`	The bank code is not recognized	Verify the code against the supported bank list
`"Invalid Account"`	The account number is incorrect or inactive	Double-check the account number with the recipient
`"Account number should be 10 values"`	Account number is not 10 digits (NGN only)	Pass a valid 10-digit NUBAN number

Apple Pay & Google Pay errors

Error message	Cause	Fix
`"Kindly check the provided Authorization"`	Invalid or incorrectly formatted API key	Re-encode your key and use the `Payaza <key>` format
`"Transaction Reference already exists"`	Reused `transaction_reference`	Generate a unique reference per transaction
`"Payment option can be either GOOGLEPAY or APPLEPAY"`	Invalid `payment_option` value	Pass `"GOOGLEPAY"` or `"APPLEPAY"` exactly
`"Payment option is currently not available via this channel"`	Unsupported currency for wallet payments	Use a supported currency code
`"Transaction not found"`	The `transaction_reference` does not match any record	Verify the reference is correct

General tips

Always use unique transaction references

Generate a new transaction_reference for every request. Reusing a reference is one of the most common causes of errors — especially duplicate-reference errors on transfers and card charges. A UUID or a timestamp-prefixed string works well.

Match your API key to its environment

Test keys only work with X-TenantID: test. Live keys only work with X-TenantID: live. Mismatching them returns an authentication error.

Base64-encode your API key

Your raw API key is not valid in the Authorization header. It must be Base64-encoded first. See the Authentication guide for language-specific examples.

Still stuck?

Email support@payaza.africa with your transaction_reference and the full error response body. The support team can trace the request on their end.

Get started

Developer tools

Accept payments

Send money

Disputes & refunds

Account management

Split Settlements

Authentication errors

Transfer errors

Virtual Account errors

Card errors

Account Name Enquiry errors

Apple Pay & Google Pay errors

General tips

​Authentication errors

​Transfer errors

​Virtual Account errors

​Card errors

​Account Name Enquiry errors

​Apple Pay & Google Pay errors

​General tips

Authentication errors

Transfer errors

Virtual Account errors

Card errors

Account Name Enquiry errors

Apple Pay & Google Pay errors

General tips