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 entered is not supported. Request the customer to use a valid three-letter ISO currency code (e.g., INR) and retry the payment.

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 trying to access does not exist. This usually happens when the resource's unique identifier (e.g., payment_id, refund_id, or payment_session_id) is incorrect, deleted, or never existed in the system. Verify the identifier and try again.

refund_cannot_be_initiated

The refund request cannot be processed due to issues with the transaction or refund parameters. This may include an incorrect transaction status, exceeding the allowable refund amount, or invalid refund details. Contact support@zohopayments.com for assistance.

amount_too_large

The transaction was declined because the amount exceeded the payment processor's limit. Request the customer to contact their bank to verify the limits and try again.

invalid_value

The payment request was rejected because the details provided don’t match the expected format, range, or constraints (e.g., incorrect values or missing information). Verify the request data and ensure it follows the required format and range.

refunds_not_enabled

Refunds are not enabled for this account. Contact support@zohopayments.com for more details.

payment_already_failed

The payment attempt has already failed, and no further actions can be taken on this transaction. Request the customer retry the payment if needed.

refund_not_allowed_payment_disputed

Refunds are not allowed while the payment is under dispute. This error occurs when attempting to issue a refund before the dispute is resolved. Wait until the dispute is settled before initiating the refund.

payment_not_captured

The payment has not been captured yet, so no further actions, such as refunds, can be performed. This occurs when the payment is not finalised or completed. Ensure the payment is successful before attempting any further actions.

payment_already_refunded

The payment has already been refunded, and no further is needed. Confirm the refund status with the customer and proceed accordingly.

refund_exceeds_payment_amount

The refund amount exceeds the original transaction amount. This error occurs when the requested refund is larger than the initial payment. Verify the original transaction amount, ensure the refund does not exceed it, and try again.

amount_too_small

The transaction was declined because the amount is below the minimum required. Ensure the transaction is greater than zero for processing.

refund_exceeds_balance_amount

The refund amount exceeds your Zoho Payments account balance. This happens when the requested refund is higher than the available balance for the transaction. Verify your available balance, wait for a new payment, or adjust the refund amount accordingly and try again.

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. Contact support@zohopayments.com to learn more.

payment_authentication_failed

The payment authentication failed, and the transaction could not be completed. Ensure that all authentication steps (e.g., OTP or CVV) are successfully completed.

payment_not_authenticated

The payment could not be authenticated, preventing the transaction from proceeding. This error occurs when the payment method fails authentication checks. Request the customer to follow all authentication steps (e.g., OTP or CVV) to complete the transaction.

payment_authentication_incomplete

The payment authentication was incomplete, and the transaction could not be processed. Request the customer to complete the authentication steps (e.g., OTP or CVV) and try again.

card_authentication_error

Card authentication failed because the card details couldn't be verified. Request the customer to verify the card number, expiry date, and CVV to ensure they’re correct and try again.

payment_authentication_timeout

The payment authentication process timed out due to exceeding the allowed time limit. Request the customer to retry the transaction, ensuring the authentication process is completed within the time limit.

card_declined_by_issuer

The card was declined by the issuer, and the transaction couldn't be processed. This occurs when the card issuer rejects the payment. Request the customer contact their issuer to resolve the issue.

generic_decline

The transaction was declined due to unspecified reasons, with no further details provided. Request the customer retry the payment if needed.

lost_or_stolen_card

The card has been reported as lost or stolen, and the transaction cannot be processed. This happens when the card issuer blocks transactions for such cards. Request the customer to contact their bank and report the issue or try a different payment method.

incorrect_card_details

The transaction could not be processed because the card details provided are incorrect. This error occurs when the card number, expiration date, or CVV does not match the issuer’s records. Request the customer to verify the card details or try a valid card or different payment method.

request_not_valid

The request is invalid due to incorrect or missing required information. This error occurs when the request doesn’t meet the API's requirements. Ensure all required parameters are included and valid

insufficient_funds

The transaction could not be processed due to insufficient funds in the customer's bank account. Request the customer to check their account balance and try the payment again.

expired_card

The card used for the transaction has expired. Request the customer to verify the card details or try an alternate payment method

card_velocity_exceeded

The card has exceeded the allowed frequency or amount for transactions.

fraudulent

The transaction was declined due to suspected fraudulent activity. This happens when the issuer or processor detects patterns or data indicating potential fraud. Investigate the transaction for fraud and request customer verification if needed.

card_decline_rate_limit_exceeded

The card was declined by the bank due to too many failed attempts, exceeding the allowed limit.

payment_cannot_be_processed

The payment could not be processed due to an unknown error. Contact support@zohopayments.com for more details.

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 authorised due to an issue with the payment provider. Request the customer to retry the payment later or use a different payment method.

duplicate_transaction

A transaction with the same payment details has already been processed. Verify the transaction details to ensure it is not a duplicate. Ask the customer to retry the payment, if needed.

customer_authentication_required

Customer authentication is required to complete the payment. This error occurs when the payment processor needs the customer to verify their identity (e.g., OTP, CVV etc.,) before processing the transaction. Ensure the customer completes the necessary steps to proceed.

invalid_card_details

The transaction could not be processed because the card details provided are invalid. This may happen if the card number, CVV, or expiration date is incorrect. Request the customer to verify the card details or try a valid card or different payment method.

transaction_failed

The transaction failed while processing. Verify payment details and retry the transaction. Contact support@zohopayments.com if the issue persists.

bank_declined

The bank rejected the payment from processing. Request the customer contact their bank to resolve the issue or try a different payment method.

bank_blocked

The transaction was blocked by the bank. Request the customer contact their bank to resolve the issue or try a different payment method.

declined_by_customer

The customer cancelled the transaction. This happens when the customer decides to abort the process. Request the customer to retry the payment if needed.

net_banking_transaction_declined_unknown_reason

The net banking transaction was declined for an unknown reason. Request the customer retry the transaction using a different payment method or contact their bank for further details.

request_time_out

The request has timed out. Request the customer to retry the transaction.

invalid_payment_link

The payment link is invalid or has expired. This error occurs when the payment link is no longer valid.

invalid_expiry_time

The expiry time provided is invalid. This error occurs when the specified expiry time does not meet the required format or constraints.

payment_link_cannot_be_updated

The payment link cannot be updated because it has already been paid, or cancelled, or is in a state that does not allow modifications. This error occurs when attempting to change the details of a payment link that is no longer editable.

payment_attempt_failed

The payment attempt was declined by the acquirer. This occurs when the acquiring bank or payment processor rejects the payment request. Request the customer to verify their payment details and try again, or contact support@zohopayments.com if the issue persists.

Refer to our developer documentation for the list of error types and how to resolve them.