The possible errors returned from Korapay’s API can be grouped into three main categories - General errors, Payout errors and Pay-in errors.

General Errors

Internal Server Error
This response does not indicate any error with your request, so you can requery the transaction to get a final status or you can report this to us.

Invalid authorization key
This response does not indicate any error with your request. Requery the transaction to get the final status.

Invalid request data
This error occurs when the request is sent with invalid data, more details of the error can be found in the data object which is also sent back as a response. Try the request again once the errors returned in the data object is resolved.

Pay-In Errors

Charge not found
This error occurs when the deposit order ID sent in the request does not exist on our system. This can be treated as a failed transaction.

Duplicate payment reference
This error occurs when the reference sent in the request has already been used for a previous transaction.

*You can see more specific API errors under the guide for each pay-in type.

Payout Errors

Errors that occur before the Payout is initiated

Unable to resolve bank account
This error occurs when our system is unable to successfully validate a customer’s bank account to determine if it’s valid or not. This can be treated as a failed withdrawal. There would be no need to query for a final status as the withdrawal would not exist on our system. Querying the withdrawal will return the error “Transaction not found”.

Transaction not found
This error occurs when the withdraw order ID attached to the request does not exist on our system. This can be treated as a failed transaction

Invalid account
This error occurs when the bank account details provided for a withdrawal is not valid. This can be treated as a failed transaction. There would be no need to query for a final status as the transaction would not exist on our system. Querying the withdrawal will return the error “Transaction not found”.

Invalid bank provided
This error occurs when the destination bank provided for withdrawal is not supported on our system or the bank code is invalid. This can be treated as a failed transaction. There would be no need to query for a final status as the transaction would not exist on our system. Querying the withdrawal will return the error “Transaction not found”

Insufficient funds in disbursement wallet
This error occurs when the funds available in your wallet is not enough to process a withdrawal request. This can be treated as a failed withdrawal. Try the request again with a new order ID once funds have been added to your wallet.

Duplicate Transaction Reference. Please use a unique reference
This error occurs when the reference sent in the request has already been used for a previous transaction.

Reasons a Payout could fail after it is initiated

After a payout is initiated, it is possible to get any of the following error responses when you query the transaction using the payment reference.

Insufficient funds in disbursement wallet
This means that the funds available in your merchant wallet are not enough to process the transaction. Try the request again with a new order ID once funds have been added to your wallet

Dormant account
This means that the destination bank account details provided has been marked as dormant by the destination bank and is unable to accept payments for that purpose. Try the request again with a new reference and bank details or have the customer reach out to their bank for further assistance.

Timeout waiting for response from destination
This means that the destination bank did not respond on time. Have the customer try again at a later time or with a different bank.

Destination bank is not available
This means that the destination bank could not be contacted. Have the customer try again at a later time or with a different bank.

Payout terminated due to suspected fraud
This means that the transaction was flagged as fraudulent.

Do not honor
This means that the bank declined the transaction for reasons best known to them, or when a restriction has been placed on a customer’s account. Try the request again at a later time with a new reference or have the customer provide a different bank.

If the problem persists, please advise the customer to contact their bank.

Payout limit exceeded
This means that the transaction being attempted will bring the customer's bank balance above the maximum limit set by their bank or that they have exceeded their limit for that day. Try the request again with a new reference or have the customer provide a different bank.

Unable to complete this transaction
This means the transaction could not be completed successfully due to downtime with the payment switch as of when the transaction was attempted. Try the request again with a new reference at a later time.

Invalid transaction
This is an error from the payment switch. Try the request again with a new reference.

Payout failed
This means the transaction could not be completed successfully for some unknown reason. Try the request again with a new reference