# Decline codes (/en/integrate/errors/decline-codes) Issuer-level decline reasons returned in `lastPaymentError.declineCode`. Plus how to read the raw `networkDeclineCode` passthrough. This page is the destination of every `lastPaymentError.docUrl` whose code came from `DeclineCode`. Anchors here match the `declineCode` value, so `https://docs.xpay.app/integrate/errors/decline-codes#insufficient_funds` lands directly on the row below. The decline code is the **issuer's** reason for refusing the charge, normalized into XPay's vocabulary. It's set on card declines only; for non-card payment failures, `lastPaymentError.declineCode` is `null` and you read `code` instead. See [Payment error codes](/integrate/errors/payment-error-codes). ## Reading `networkDeclineCode` [#reading-networkdeclinecode] Alongside `declineCode`, every card decline carries a `networkDeclineCode`: a 2-4 digit code returned by the card network (the literal code from the ISO 8583 message, ICCNetwork advice, or equivalent depending on the card brand). Two things to know: * **The meaning is brand-specific.** A `51` from a Visa means "insufficient funds" but the same code on a different network may map to something else entirely. Take the card's brand into account when interpreting the raw code. * **It's a passthrough, not a normalization.** XPay does not translate `networkDeclineCode` into a customer-friendly message. Use it for support escalation or post-mortem analysis, not for runtime branching. For runtime branching, use `declineCode` (XPay's normalized vocabulary, listed below) and `adviceCode` (the action token described in [Payment errors](/integrate/errors/payment-errors)). Treat `networkDeclineCode` as a breadcrumb for support tickets. ## Common declines [#common-declines] The most frequent reasons issuers return. ### `generic_decline` [#generic_decline] The issuer declined without a specific reason. Often a fallback when the issuer's risk model rejects but doesn't tell us why. ### `insufficient_funds` [#insufficient_funds] The customer's available balance can't cover the charge. ### `lost_card` [#lost_card] The card was reported lost. Don't retry; the issuer has flagged the card. ### `stolen_card` [#stolen_card] The card was reported stolen. Don't retry. ### `expired_card` [#expired_card] The card has expired. The customer needs to use a different card. ### `incorrect_cvc` [#incorrect_cvc] The CVC/CVV the customer entered doesn't match what the issuer has on file. ### `incorrect_number` [#incorrect_number] The card number passed format checks but the issuer says it's wrong. ### `incorrect_zip` [#incorrect_zip] The postal code on the customer's billing address doesn't match what the issuer has on file. ### `incorrect_address` [#incorrect_address] The street address didn't match. AVS check failed. ## Authentication [#authentication] 3D Secure and step-up authentication outcomes. ### `authentication_required` [#authentication_required] The issuer is requiring 3D Secure authentication. The customer needs to complete the challenge. ### `authentication_not_handled` [#authentication_not_handled] The customer skipped or didn't complete a required authentication step. ### `mobile_device_authentication_required` [#mobile_device_authentication_required] The card requires the customer to re-authenticate on a mobile device (e.g. tap-to-pay biometric). ## Processing [#processing] The issuer accepted the request but rejected at processing time. ### `processing_error` [#processing_error] A generic processing error from the issuer's side. Often transient. ### `do_not_honor` [#do_not_honor] The issuer returned "do not honor" without further detail. Usually means the customer should contact their bank. ### `call_issuer` [#call_issuer] The issuer told the customer to contact them directly. Surface a clear "call your bank" prompt to the customer. ### `card_not_supported` [#card_not_supported] The card doesn't support this type of purchase (for example, certain debit cards reject some merchant categories). ### `currency_not_supported` [#currency_not_supported] The card's account doesn't support the transaction currency. ### `duplicate_transaction` [#duplicate_transaction] The issuer detected a near-identical transaction recently and refused as a duplicate. ### `approve_with_id` [#approve_with_id] A specific issuer response that effectively means "we'd approve this with extra ID." Usually safe to surface a "try again" prompt. ## Limits [#limits] The card or account hit a limit. ### `card_velocity_exceeded` [#card_velocity_exceeded] The card has been used too many times in a short window. The issuer is rate-limiting. ### `withdrawal_count_limit_exceeded` [#withdrawal_count_limit_exceeded] The card hit its per-period withdrawal/transaction count limit. ## Fraud and risk [#fraud-and-risk] The issuer or the network flagged the charge for risk. ### `fraudulent` [#fraudulent] Suspected fraud. Don't retry. ### `merchant_blacklist` [#merchant_blacklist] The card is blocked specifically for your merchant account. ### `pickup_card` [#pickup_card] The issuer is asking that the card be physically picked up. Don't retry. ### `restricted_card` [#restricted_card] The card has restrictions that prevent this transaction. ### `security_violation` [#security_violation] A security check failed at the issuer or network level. ## Account issues [#account-issues] The card account itself has a problem unrelated to this specific transaction. ### `invalid_account` [#invalid_account] The card account is invalid as far as the issuer is concerned. ### `new_account_information_available` [#new_account_information_available] The card has been reissued. The issuer is signaling that the customer has new card details. ### `transaction_not_allowed` [#transaction_not_allowed] The issuer doesn't allow this kind of transaction on this card. ### `service_not_allowed` [#service_not_allowed] The merchant or service isn't allowed for this card. ### `not_permitted` [#not_permitted] A general "not permitted" response from the issuer. ## PIN [#pin] PIN-related declines mostly surface for in-person or PIN-on-file transactions; rare in standard e-commerce flows but listed for completeness. ### `incorrect_pin` [#incorrect_pin] The PIN entered didn't match. ### `invalid_pin` [#invalid_pin] The PIN format is invalid. ### `pin_try_exceeded` [#pin_try_exceeded] The cardholder has exceeded the maximum number of PIN attempts. ### `offline_pin_required` [#offline_pin_required] The card requires offline PIN entry, which isn't available in this flow. ### `online_or_offline_pin_required` [#online_or_offline_pin_required] The card requires PIN entry (online or offline) and didn't get one. ## Amount [#amount] ### `invalid_amount` [#invalid_amount] The transaction amount itself was rejected by the issuer (often falls outside per-transaction limits configured on the card). ## Revocation [#revocation] Customer-initiated stops on automatic charges. ### `revocation_of_authorization` [#revocation_of_authorization] The cardholder has revoked authorization for this specific recurring charge. ### `revocation_of_all_authorizations` [#revocation_of_all_authorizations] The cardholder has revoked authorization for all recurring charges from this merchant. ### `stop_payment_order` [#stop_payment_order] The customer has issued a stop payment. ### `no_action_taken` [#no_action_taken] The issuer didn't process the transaction at all. Usually a transient state; safe to retry. ### `reenter_transaction` [#reenter_transaction] The issuer is asking the merchant to re-submit the transaction. ## Test mode [#test-mode] ### `testmode_decline` [#testmode_decline] This decline only fires in test mode. Use the test card matrix on [Test mode and test cards](/get-started/test-mode) to drive specific decline outcomes during development. ## Where to next [#where-to-next] The other reference for failed payments: `lastPaymentError.code` values. The model: how `lastPaymentError` is shaped, plus the `adviceCode`-driven handler pattern. The reference for errors returned in HTTP responses to your API calls. The synchronous error envelope. Back to the top. The two-surfaces map.