When your Remote Host Authorization (RHA) integration rejects a transaction, you must respond with one of the error codes listed below.
Each error code includes guidance on when to use it and whether the acquirer merchant is allowed to reattempt the transaction.
For the full Remote Host Authorization API specification, see Remote Host Authorization.
Error Codes
The table below can be scrolled horizontally.
| Error Code | Description | Use When | Usage Limitation | Merchant Reattempt Allowed (Visa) |
|---|---|---|---|---|
CARD0000- Internal Server Error | Client's remote host server faces an internal or unknown error. Unable to process transaction. | Internal/unknown errors, software/code exceptions, server failures. | N/A | Yes |
CARD0001 - Insufficient Balance | Cardholder does not have enough balance to complete the transaction. On CARD0001 reject, please prompt the cardholder to top-up their balance. | Balance check fails, insufficient funds. | N/A | Yes |
CARD0002 - Duplicate Transaction ID | The transaction reference ID has already been used. | Duplicate authorization request detected. | N/A | Yes |
| CARD0003 - Transaction Not Found | The referenced original transaction cannot be found. | Reversal/completion references a non-existent transaction. | N/A | Yes |
CARD0004 - Card Not Found | The card/account is already closed or does not exist in the remote host system. | Card already closed, lookup failed, account not registered. | N/A | No |
CARD0005 - Unauthorized | The request is not authorized (authentication failure). | Invalid API key, expired token, permission denied. | N/A | Yes |
CARD0006 - Card Restriction | The card is restricted due to country/region-related policies. | Transaction attempted from a restricted country, OFAC/sanctions block. | N/A | Yes |
CARD0007 - Suspected Fraud | The transaction failed one or more fraud rules in the client's fraud detection system. | Velocity checks, fraud scoring, suspicious pattern detected. | N/A | Yes |
CARD0008 - Violation of Law | The transaction is rejected due to regulatory or legal restrictions. | Gambling restrictions, cryptocurrency restrictions, regulatory compliance blocks. | N/A | Yes |
CARD0009 - Transaction Not Supported / Blocked by Issuer | The issuer has blocked this transaction due to restrictions on issuer or card product-level. Must not be used for blocks on a single card. Cardholder cannot change/exempt themselves from this restriction. | Transaction type not supported (e.g., Cash withdrawal disabled, magnetic stripe disabled), issuer policy blocks. | N/A | Yes |
CARD0010 - Blocked by Cardholder | Cardholder has imposed certain restrictions on their card and can undo it themselves. | Cardholder-configured restrictions (e.g., online transactions disabled, one or more acquirer currencies blocked). | N/A | Yes |
CARD0011 - Card Lost | Card has been reported lost. Cardholder cannot undo this. | Card reported lost, requires replacement card. | N/A | No |
CARD0012 - Card Stolen | Card has been reported stolen. Cardholder cannot undo this. | Card reported stolen, requires replacement card. | N/A | No |
CARD0013 - Card Suspended | Card is suspended/frozen. Cardholder can reactivate it themselves. | Temporary card freeze via app or customer service (cardholder-initiated). | N/A | Yes |
CARD0014 - Invalid Merchant | The acquirer merchant or MCC is not valid or not allowed for this card under client/card product. Used for blocks by both issuer policy and cardholder preference. | Acquirer merchant or MCC is blocked due to issuer policy or cardholder preference. | N/A | Yes |
CARD0015 - Cash Withdrawal Amount Exceeded | The cash withdrawal amount exceeds the allowed limit. | Cash withdrawal amount exceeds single transaction or daily limit. | Only use for cash withdrawals (transaction_type == "deduction" && metadata.processing_code.StartsWith("01")) | Yes |
CARD0016 - Cash Withdrawal Velocity Exceeded | The cash withdrawal frequency exceeds the allowed limit. | Too many cash withdrawals within a time period. | Only use for cash withdrawals (transaction_type == "deduction" && metadata.processing_code.StartsWith("01")) | Yes |
CARD0017 - Stop This Payment | The acquirer merchant will be instructed to stop this specific recurring payment (by cardholder preference or on behalf of them). | Repeat insufficient balance for recurring payment, stop future attempts (by cardholder preference or on behalf of them). To stop recurring payments from certain merchants/MCCs or to stop ALL recurring payments for one or more cards, please reach out to us for assistance. | Only use for recurring payments (metadata.electronic_commerce_indicator == "02"). | No |
FAQ
What should I return if my error doesn't fit any code above?
Use CARD0000 for internal or unknown errors. For known rejections related to your internal policies that don't fit into any other available error code, use CARD0009 for issuer/product-level blocks, or CARD0010 if the block applies to a single card and/or was configured by the cardholder themselves (i.e., the cardholder can undo it anytime).
What does "Merchant Reattempt Allowed" mean?
It indicates whether the acquirer merchant is permitted to reattempt recurring transaction in the future (e.g., tomorrow, the day after). If "No", the acquirer merchant will be prompted to stop re-attempting the recurring transaction.
What's the difference between CARD0009 and CARD0010 error code?
-
CARD0009is for issuer/product-level policy blocks that the cardholder cannot override. -
CARD0010is for issuer or cardholder-initiated blocks that cardholder can opt-out or unblock themselves from.
What's the difference between CARD0011, CARD0012, and CARD0013 error codes?
-
CARD0011(lost) andCARD0012(stolen) are permanent. The card must be replaced. -
CARD0013(suspended) is temporary, and the cardholder can reactivate it themselves.