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.

insufficient_customer_details

The transaction failed due to missing or incomplete customer details. Ensure all required information is provided before retrying.

customer_max_payment_methods

The customer has reached the maximum number of payment methods allowed (100). Remove one to add a new method.

invalid_payment_method_usage

The payment method provided is invalid. Enable it under Settings > Payment Methods and try again.

payment_method_not_associated_to_customer

No payment method is associated with the customer. Please associate a valid method and try again.

payment_method_unactivated

The selected payment method is currently inactive. Request the customer to use an active method and try again.

payment_method_type_not_supported

The selected payment method type is not supported. Use a different method to proceed.

payment_method_expired_for_authorization

The authorization period for this payment method has expired. Initiate a new payment request.

payment_method_cannot_be_updated

This payment method cannot be updated because it wasn’t successfully added. Try adding the payment method again.

payment_method_cannot_be_deleted

The payment method cannot be deleted as it was not successfully added.

payment_method_cannot_be_saved

The payment method cannot be saved for future transactions. Use it only for one-time payments.

payment_method_details_not_associated_to_customer

The payment method details are not linked to the specified customer. Associate the method and try again.

invalid_payment_method_type_for_update

The payment method type is not valid for updates. Choose a supported type and try again.

payment_not_authorized

The payment could not be processed as the customer hasn’t authorized it.

payment_authorization_stopped

Payment could not be processed as the authorization for this payment was revoked by the customer.

payments_not_enabled

Payments cannot be processed as the payment methods have not been enabled. Contact your merchant to enable the payment methods.

invalid_currency

The currency entered is invalid. Request the customer to use a valid three-letter ISO currency code (e.g., USD) and retry the payment.

currency_not_supported_for_payment

This currency is currently not supported. Use a supported currency and try again.

payment_already_failed

The payment attempt has already failed, and further actions cannot be performed. Request the customer to retry the payment.

payment_authentication_failed

Payment authentication failed. Ensure the customer completes all authentication steps.

payment_not_authenticated

The payment couldn’t be processed as it couldn’t be authenticated.

payment_authentication_incomplete

The payment couldn't be processed as the authentication was incomplete.

payment_authentication_timeout

Payment authentication timed out. Please retry the transaction.

payment_cannot_be_processed

The payment could not be processed. Contact support for assistance.

payment_attempt_failed

The payment was rejected by the acquiring bank. Verify the payment details and try again, or contact support for more details.

payment_attempt_expired

The payment attempt expired. Try initiating the payment again.

refund_cannot_be_initiated

We couldn’t process your refund request due to invalid details. This can include invalid transaction status, exceeding the refundable amount, or incorrect refund parameters. Contact support for assistance.

refund_not_allowed_payment_disputed

Refunds are not allowed as the payment has been disputed already.

payment_already_refunded

This payment has already been refunded. Additional refunds cannot be processed.

refund_exceeds_payment_amount

The refund amount exceeds the original payment amount. Adjust the amount and try again.

refund_exceeds_balance_amount

The requested refund exceeds the remaining transaction balance. Check your available balance, wait for a new payment, top up your reserve, or adjust the refund amount 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. Contact support@zohopay.com for assistance.

refunds_not_enabled

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

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.

amount_too_small

The transaction was declined because the amount is too small. Ensure the transaction is greater than zero for processing.

card_authentication_error

Card authentication failed. Request the customer to verify the card number, expiry, and CVV and retry.

card_declined_by_issuer

The card issuer declined the transaction. Request the customer to contact their issuer for more details or try a different card.

generic_decline

The transaction was declined. Try again or use a different payment method.

lost_or_stolen_card

Transaction cannot be processed as the card has been reported lost or stolen.

incorrect_card_details

Transaction cannot be processed as the card details entered are incorrect.

expired_card

The card has expired.

card_velocity_exceeded

Transaction declined as the card limits have been exceeded.

fraudulent

The transaction was blocked due to suspected fraud, based on patterns or data flagged by the issuer or processor.

card_decline_rate_limit_exceeded

The card has been declined too many times in a short period. Try again later or use a different payment method.

invalid_card_details

The card number, CVV, or expiry date entered is invalid.

incorrect_bank_account_details

The bank account details are incorrect or invalid.

bank_account_declined

The bank account is either not verified or does not support online payments. Use a different method.

bank_account_exists

This account is already linked to another customer. Use a different account.

bank_account_unusable

The account doesn't support ACH payments.

bank_account_closed

The customer’s bank account has been closed.

bank_account_frozen

The customer's bank account is frozen.

payment_method_unverified

This payment method couldn’t be verified. Add another method and try again.

request_not_valid

The request is invalid or missing required fields. Check your request format and try again.

request_time_out

The session timed out. Initiate the transaction again.

resource_does_not_exist

The requested resource (e.g., payment_id) doesn’t exist or has been deleted. Check the unique identifier (e.g., payment_id, refund_id, or payment_session_id) and try again.

reenter_transaction

The transaction couldn’t be processed. Ask the customer to re-enter the details and try again.

duplicate_transaction

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

customer_authentication_required

Customer authentication is required. Ensure the customer completes it to proceed.

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.

issuer_not_available

The payment could not be processed as the issuer couldn’t be reached. Try again later or use another method.

declined_by_customer

The transaction was canceled by the customer.

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.