The possible errors returned from Korapay’s API can be grouped into three main categories - General errors, Payout errors, Pay-in errors, and Refund 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”

Invalid mobile money operator.
This error occurs when the mobile money operator provided for mobile money payout is not supported on our system or the operator 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

Refund Initiation Errors

Transaction has not yet been settled
This means that the transaction you are attempting to refund has not yet been settled to your balance. Until the transaction is settled, funds cannot be reversed. Please attempt the refund again after the expected settlement date.

Refund can only be requested on a successful transaction
This means that the original transactions wasn't processed successfully. You can only request a refund for a transaction that was successfully processed.

Transaction not found
This error occurs when the transaction reference submitted for the refund does not exist on our system. This can be treated as a failed refund.

Refund already exists with reference **reference submitted**
This error occurs when the reference sent in the request has already been used for a previously initiated refund. Please attempt the refund again with a different reference.

Refund not supported for this currency, please contact support
This error occurs when refund is not supported for the transaction currency. Please get in touch with our support team. They'll be able to guide on how to proceed.

Refund amount cannot be more than **{currency} {transactionAmountCollected}**
This means that the refund amount provided exceeds the value of the original successful transaction amount. Please update the refund amount you are trying to process and try again

Refund amount cannot be less than **{currency} {minimumRefundAmount}**
This means that the refund amount specified is below the minimum allowed value for processing. The system enforces a minimum refund amount for the currencies supported as shown here. Please get in touch with our support team if you need this reviewed

A full reversal has already been processed for this transaction
This means that a reversal equivalent to the original transaction amount has already been successfully initiated. Please verify the details of the reversal(s) on the transaction details page of the dashboard

A full refund cannot be initiated for this transaction. Please enter an amount less than or equal to **{currency} {transactionAmountCollected}**
This error occurs when no refund amount is passed in the request and the system tries to process a full refund but the total remaining refundable amount for the transaction is less than amount collected. To resolve this, please enter the specific amount you wish to refund. This amount must be less or equal to the amount left to be refunded.

The maximum refundable amount for this transaction is **{currency} {transactionAmountCollected minus amountAlreadyReversed}**
This error occurs when the amount requested to be refunded is more than the maximum refundable amount. To resolve this, please enter the specific amount you wish to refund. This amount must be less or equal to the amount left to be refunded.

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