Errors

Zoho Payments uses HTTP status codes to display the result of an API call. Generally, 2xx class codes are success codes, 4xx class codes occur when the information provided by the client is incorrect, and 5xx class codes indicate server-side errors.

The status codes that are commonly used are listed below:

HTTP Status Codes

Status Code	Description
200	OK
201	Created
400	Bad request
401	Unauthorized (Invalid AuthToken)
404	URL Not Found
405	Method Not Allowed (Method you have called is not supported for the invoked API)
429	Rate Limit Exceeded (API usage limit exceeded)
500	Internal Error

Error Codes

Zoho Payments Error codes and their detailed messages.

payments_not_enabled

Payments cannot be processed because no payment methods are enabled for your account. This error occurs when there are no active payment methods available for transaction processing.

invalid_currency

The currency you have entered is invalid. Ensure that you enter a valid currency code. Accepted format for currency Three-letter ISO code.

currency_not_supported_for_payment

A payment is attempted with a currency other than INR. Using other currencies will trigger this error.

resource_does_not_exist

The resource you are attempting to access does not exist. This error typically occurs when the client requests a resource by its unique identifier (e.g., payment_id, refund_id or payment_session_id) that is either incorrect, has been deleted, or never existed in the system.

refund_cannot_be_initiated

The refund request cannot be initiated due to one or more issues with the transaction or the refund parameters. The refund cannot be initiated due to the transaction's status, exceeding the allowable refund amount, or invalid refund details. Please write to support@zohopayments.com to learn more.

amount_too_large

The transaction was declined because the processing amount exceeded the payment processor's limit, which is not explicitly specified, making it unprocessable.

invalid_value

The request was rejected due to invalid values that do not meet the expected format, range, or constraints. Please verify the details and try again.

refunds_not_enabled

Refunds are not enabled for this account. This error occurs when the refund functionality is not activated or allowed. Contact support@zohopayments.com for more details.

payment_already_failed

The payment has failed already, and no further processing can be done on this failed transaction.

refund_not_allowed_payment_disputed

Refunds are not allowed because the payment is currently under dispute. This error occurs when attempting to issue a refund while a dispute is ongoing.

payment_not_captured

The payment has not been captured yet, so action likes refunds cannot be processed. This error occurs when attempting to perform actions on a payment that has not been finalized or completed.

payment_already_refunded

The payment has already been refunded, and no further refunds can be processed for this transaction.

refund_exceeds_payment_amount

The refund amount exceeds the actual amount that can be refunded. This error occurs when the requested refund is larger than the amount initially paid. Please verify the amount and try again.

amount_too_small

The processing amount is too small and does not meet the minimum threshold required by the processor. This error occurs when the amount is below the processor's minimum limit..

refund_exceeds_balance_amount

The refund amount exceeds the remaining transaction balance. This error occurs when the requested refund is greater than the available balance for the transaction.

refund_cannot_be_initiated_due_to_insufficient_balance

The refund cannot be initiated due to insufficient funds in your Zoho Payments account balance. The available balance is lower than the requested refund amount.Please write to support@zohopayments.com to learn more.

payment_authentication_failed

Payment authentication failed, and the transaction could not be completed. This error occurs when the authentication process for the payment method does not succeed.

payment_not_authenticated

The payment could not be authenticated, preventing the transaction from proceeding. This error occurs when the payment method fails authentication checks.

payment_authentication_incomplete

Payment authentication is incomplete, and the transaction cannot be processed. This error occurs when the authentication process for the payment method is not fully completed.

card_authentication_error

Card authentication failed, preventing the transaction from being processed. This error occurs when the card details cannot be verified or authenticated.

payment_authentication_timeout

The payment authentication process timed out. This error occurs when the authentication process takes too long and exceeds the allowed time limit.

card_declined_by_issuer

The card was declined by the issuer, and the transaction cannot be processed. This error occurs when the card issuer rejects the transaction.

generic_decline

The transaction was declined for unspecified reasons. This error occurs when the payment is rejected but no specific decline reason is provided.

lost_or_stolen_card

The card has been reported as lost or stolen, and the transaction cannot be processed. This error occurs when the card issuer blocks transactions for cards flagged as lost or stolen.

incorrect_card_details

The card details provided are incorrect or invalid. This error occurs when the card number, expiration date, or CVV does not match the issuer’s records.

request_not_valid

The request is not valid due to incorrect or missing required information. This error occurs when the request does not meet the API's requirements.

insufficient_funds

The transaction cannot be processed because the customer’s bank account used for the payment has insufficient funds. This error occurs when there is not enough money in the account to cover the transaction amount.

expired_card

The card used for the transaction has expired. This error occurs when the card's expiration date is past the current date.

card_velocity_exceeded

The transaction was declined because the card has exceeded its permitted transaction frequency or amount.

fraudulent

The transaction was declined due to suspected fraudulent activity. This error occurs when the system detects patterns or data indicative of fraud.

card_decline_rate_limit_exceeded

The card has been declined too many times in a short period, exceeding the allowed decline rate.

payment_cannot_be_processed

The payment could not be initiated. Please contact support for more details and assistance.

reenter_transaction

Payment could not be processed due to an unknown error. Please re-enter the transaction details and try again. If the issue persists, advise your customer to verify their information and attempt the transaction again.

issuer_not_available

The payment could not be processed because the card issuer could not be reached to authorize the payment. Please try again later.

duplicate_transaction

A similar amount was recently processed using the same card details. Please verify if this might be a duplicate transaction before attempting it again.

customer_authentication_required

Customer authentication is required to complete this payment. Please ensure that the customer completes the necessary authentication steps to proceed with the transaction.

invalid_card_details

The request contains invalid card details. This error may occur if the card number, CVV, or expiration date provided is incorrect.

transaction_failed

The payment failed while processing. If the problem persists, contact support@zohopayments.com for assistance.

bank_declined

The transaction was declined by the bank. This error occurs when the bank rejects the payment.

bank_blocked

The transaction was blocked by the bank. We recommend advising your customer to contact their bank or use an alternative payment method.

declined_by_customer

The transaction was declined because the funds transfer was canceled by the user. This error occurs when the customer decides to abort the transaction.

net_banking_transaction_declined_unknown_reason

The net banking transaction was declined for an unknown reason. This error occurs when the payment is rejected by the bank without providing a specific decline reason.

request_time_out

The session has expired, and the transaction cannot be processed. This error occurs when the request took too long to complete, leading to the expiration of the session.

payment_attempt_failed

The payment attempt was rejected by the acquirer. This error occurs when the payment request is declined by the acquiring bank or payment processor.