Payment error and decline code dictionary

Approved or completed successfully

The issuer approved the transaction. A field 39 of 00 is the only unambiguous success value in ISO 8583 — every other code is a decline, a referral or an error.

Refer to card issuer

The issuer will not decide automatically and wants the merchant to call for a voice authorisation. It is not a decline on its own, but at any unattended terminal it is one in practice.

Invalid merchant

The merchant identifier in the message is not one the issuer or the network recognises. This is a configuration fault on the acquiring side, not a problem with the card.

Pick up card

The issuer is declining and instructing the merchant to retain the card. It is a hard decline, and the specific reason is deliberately not disclosed to the merchant.

Do not honour

The issuer refused the transaction and did not say why. It is the most common decline in card processing, and it is deliberately uninformative — 05 is what an issuer sends when it does not want to disclose its reason.

Invalid transaction

The issuer understood the message but will not accept this kind of transaction on this account. It usually means the processing code, the message type, or the combination of the two is one the issuer does not support.

Invalid amount

The amount field is malformed or outside what the issuer will accept. Nearly always a formatting fault: ISO 8583 amounts are fixed-length, zero-padded minor units with no decimal point.

Invalid card number (no such number)

The primary account number does not correspond to an account the issuer knows. The card number is either mistyped, malformed, or routed to an issuer that does not own that range.

Lost card

The card has been reported lost by the cardholder and the issuer is instructing that it be retained. A final decline that will not succeed on any retry.

Stolen card

The card has been reported stolen and the issuer is instructing that it be retained. Final, and never worth retrying.

Not sufficient funds

The account exists and is in good standing but does not have the balance or credit available to cover this transaction. One of the few declines where a later retry can legitimately succeed.

Expired card

The expiry date on the card has passed, or the date sent does not match what the issuer has on file. A hard decline that only new card details will fix.

Incorrect PIN

The PIN entered does not match the one on file for the account. In practice, at least as often a PIN block or key problem on the acquiring side as a genuinely mistyped PIN.

Transaction not permitted to cardholder

The card is valid and the message is well formed, but this cardholder is not allowed to perform this type of transaction. A restriction on the card product, not a shortage of funds.

Transaction not permitted to terminal

The acquirer or issuer will not accept this transaction type from this terminal or merchant. A configuration fault on the accepting side, so it fails for every card equally.

Exceeds withdrawal amount limit

The amount is above a per-transaction or per-period ceiling on the account. The card is good and funded; the limit is what refused it.

Restricted card

The issuer has a restriction on the card that prevents this transaction — commonly a country, merchant-category or account-level block rather than anything about the amount.

Exceeds withdrawal frequency limit

Too many transactions on this card within the issuer's counting window. It caps the number of transactions rather than their value, which is what separates it from 61.

Allowable number of PIN tries exceeded

The PIN retry counter on the card or at the issuer has been exhausted. The card is locked for PIN transactions until the cardholder unblocks it.

Issuer or switch is inoperative

The issuer's authorisation system could not be reached. Nothing is wrong with the card or your message — the decision could not be obtained, so the transaction failed by default.

System malfunction

Something failed inside the acquirer, network or issuer while processing the message. A generic infrastructure error rather than a decision about the card.

card_declined

The card was declined by the issuer. `card_declined` is an error code, not a decline code — the reason for the decline is in the `decline_code` attribute on the same error, and that is the value you actually need to look up.

do_not_honor

Stripe's wording is exact and deliberately unhelpful: "The card was declined for an unknown reason." The issuer refused the payment and disclosed nothing about why, and Stripe cannot tell you more than the issuer told it.

generic_decline

Stripe documents this as: the card was declined for an unknown reason, or Stripe Radar or Adaptive Acceptance blocked the payment. Unlike `do_not_honor`, this one can mean the payment never reached the issuer at all.

insufficient_funds

Stripe's wording: "The card has insufficient funds to complete the purchase." The card is valid and the account is in good standing — there is simply not enough available balance or credit.

expired_card

Stripe's wording: "The card has expired." The documented next step is short — the customer needs to use another card. No retry of the same details will succeed.

incorrect_cvc

Stripe's wording: "The CVC number is incorrect." The customer needs to try again using the correct CVC. There is a separate `invalid_cvc` with the same description — the difference is whether the value was wrong or malformed.

processing_error

Stripe's wording: "An error occurred while processing the card." The documented next step is to attempt the payment again, and if it still cannot be processed, to try again later. One of the genuinely transient codes.

issuer_not_available

Stripe's wording: "The card issuer couldn't be reached, so the payment couldn't be authorised." Attempt the payment again; if it still fails, the customer needs to contact their card issuer.

fraudulent

Stripe's wording: "The payment was declined because Stripe suspects that it's fraudulent." Stripe is explicit about how to handle it — do not report more detailed information to your customer; present it the same way as a generic decline.

lost_card

Stripe's wording: "The payment was declined because the card has been reported as lost." The specific reason should not be reported to the customer — present it as a generic decline.

stolen_card

Stripe's wording: "The payment was declined because the card is reported stolen." As with a lost card, do not report the detail to your customer — present it in the same manner as a generic decline.

card_velocity_exceeded

Stripe's wording: "The customer has exceeded the balance, credit limit, or transaction amount limit available on their card." The customer needs to contact their card issuer for more information.

authentication_required

The card was declined because the transaction requires authentication such as 3-D Secure. It is not a refusal of the payment — it is a request for the cardholder to prove who they are, and the payment can usually still complete.

testmode_decline

Stripe's wording: "A Stripe test card number was used." A genuine card must be used to make a payment. This means a test card reached live mode — nothing is broken with the card or the issuer.

BAD_REQUEST_ERROR

The request was malformed, unauthorised, or referred to something that does not exist. It is the broadest of Razorpay's three error codes and covers most client-side faults, so the useful detail is in the `description` and `reason` fields rather than in the code itself.

GATEWAY_ERROR

The request could not be completed because of an error at the payment gateway or the downstream bank. It is not your request that is wrong — something further along the chain failed, and Razorpay's guidance is to retry with the same idempotency key and request body.

SERVER_ERROR

An unexpected error occurred on Razorpay's side while processing the request. Their documented description is "We are facing some trouble completing your request at the moment. Please try again shortly." — it is transient and the remedy is a retry.