Skip to main content
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
}
CauseFix
Missing or empty Authorization headerAdd Authorization: Payaza <base64-encoded-key> to every request
API key not Base64-encodedEncode 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 versaMatch the key to its environment
Key was regenerated on the dashboardCopy the new key, re-encode it, and update your integration

​
Transfer errors

Error messageCauseFix
"Payout amount is less than total credit amount"The sum of credit_amount values in payout_beneficiaries exceeds payout_amountEnsure payout_amount equals the sum of all credit_amount values
"Insufficient Balance"Your Payaza account balance is below the transfer amountTop up your account or reduce the transfer amount
"Invalid transaction pin"The transaction_pin in the request body is incorrectCorrect the PIN — see how to set your PIN
"Transaction reference already exists"A transaction_reference was reusedGenerate a unique reference for every transfer attempt
"Bank code is not correct"The bank_code value is invalidVerify the bank code against the supported bank list
"Account number can only be numbers"The account_number contains non-numeric charactersPass 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"
}
See the Transfers guide for the full integration walkthrough.

​
Virtual Account errors

Error messageCauseFix
"Transaction not found"The transaction_reference does not existVerify you are using the correct reference
"Reserved Virtual Account does not exist"The virtual account number is incorrect or was never createdCheck the account number and confirm creation succeeded
"Could not generate virtual account at the moment"Upstream network errorRetry the request. If the issue persists, contact support@payaza.africa
Sample responses 
{
  "response_code": 404,
  "response_message": "Transaction not found",
  "response_content": {
    "transaction_reference": ""
  }
}
See the Virtual Accounts guide for the full integration walkthrough.

​
Card errors

Error messageCauseFix
"There is already an authentication outcome associated with the supplied transaction ID"Duplicate transaction_referenceGenerate a new unique reference and retry
"Unable to determine card payment"Invalid or unsupported card detailsVerify the card number, expiry date, and CVV
"Expired card"The card’s expiry date has passedUse 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
}
Use Test Cards to simulate different card outcomes during development.

​
Account Name Enquiry errors

Error messageCauseFix
"Bank code should be 6 values"bank_code is not 6 digitsPass a valid 6-digit bank code as an integer
"Unknown Bank Code"The bank code is not recognizedVerify the code against the supported bank list
"Invalid Account"The account number is incorrect or inactiveDouble-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 messageCauseFix
"Kindly check the provided Authorization"Invalid or incorrectly formatted API keyRe-encode your key and use the Payaza <key> format
"Transaction Reference already exists"Reused transaction_referenceGenerate a unique reference per transaction
"Payment option can be either GOOGLEPAY or APPLEPAY"Invalid payment_option valuePass "GOOGLEPAY" or "APPLEPAY" exactly
"Payment option is currently not available via this channel"Unsupported currency for wallet paymentsUse a supported currency code
"Transaction not found"The transaction_reference does not match any recordVerify the reference is correct

​
General tips

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.
Test keys only work with X-TenantID: test. Live keys only work with X-TenantID: live. Mismatching them returns an authentication error.
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.
Email support@payaza.africa with your transaction_reference and the full error response body. The support team can trace the request on their end.