Decline codes

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.

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). Treat networkDeclineCode as a breadcrumb for support tickets.

Common declines

The most frequent reasons issuers return.

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

The customer's available balance can't cover the charge.

lost_card

The card was reported lost. Don't retry; the issuer has flagged the card.

stolen_card

The card was reported stolen. Don't retry.

expired_card

The card has expired. The customer needs to use a different card.

incorrect_cvc

The CVC/CVV the customer entered doesn't match what the issuer has on file.

incorrect_number

The card number passed format checks but the issuer says it's wrong.

incorrect_zip

The postal code on the customer's billing address doesn't match what the issuer has on file.

incorrect_address

The street address didn't match. AVS check failed.

Authentication

3D Secure and step-up authentication outcomes.

authentication_required

The issuer is requiring 3D Secure authentication. The customer needs to complete the challenge.

authentication_not_handled

The customer skipped or didn't complete a required authentication step.

mobile_device_authentication_required

The card requires the customer to re-authenticate on a mobile device (e.g. tap-to-pay biometric).

Processing

The issuer accepted the request but rejected at processing time.

processing_error

A generic processing error from the issuer's side. Often transient.

do_not_honor

The issuer returned "do not honor" without further detail. Usually means the customer should contact their bank.

call_issuer

The issuer told the customer to contact them directly. Surface a clear "call your bank" prompt to the customer.

card_not_supported

The card doesn't support this type of purchase (for example, certain debit cards reject some merchant categories).

currency_not_supported

The card's account doesn't support the transaction currency.

duplicate_transaction

The issuer detected a near-identical transaction recently and refused as a duplicate.

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

The card or account hit a limit.

card_velocity_exceeded

The card has been used too many times in a short window. The issuer is rate-limiting.

withdrawal_count_limit_exceeded

The card hit its per-period withdrawal/transaction count limit.

Fraud and risk

The issuer or the network flagged the charge for risk.

fraudulent

Suspected fraud. Don't retry.

merchant_blacklist

The card is blocked specifically for your merchant account.

pickup_card

The issuer is asking that the card be physically picked up. Don't retry.

restricted_card

The card has restrictions that prevent this transaction.

security_violation

A security check failed at the issuer or network level.

Account issues

The card account itself has a problem unrelated to this specific transaction.

invalid_account

The card account is invalid as far as the issuer is concerned.

new_account_information_available

The card has been reissued. The issuer is signaling that the customer has new card details.

transaction_not_allowed

The issuer doesn't allow this kind of transaction on this card.

service_not_allowed

The merchant or service isn't allowed for this card.

not_permitted

A general "not permitted" response from the issuer.

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

The PIN entered didn't match.

invalid_pin

The PIN format is invalid.

pin_try_exceeded

The cardholder has exceeded the maximum number of PIN attempts.

offline_pin_required

The card requires offline PIN entry, which isn't available in this flow.

online_or_offline_pin_required

The card requires PIN entry (online or offline) and didn't get one.

Amount

invalid_amount

The transaction amount itself was rejected by the issuer (often falls outside per-transaction limits configured on the card).

Revocation

Customer-initiated stops on automatic charges.

revocation_of_authorization

The cardholder has revoked authorization for this specific recurring charge.

revocation_of_all_authorizations

The cardholder has revoked authorization for all recurring charges from this merchant.

stop_payment_order

The customer has issued a stop payment.

no_action_taken

The issuer didn't process the transaction at all. Usually a transient state; safe to retry.

reenter_transaction

The issuer is asking the merchant to re-submit the transaction.

Test mode

testmode_decline

This decline only fires in test mode. Use the test card matrix on Test mode and test cards to drive specific decline outcomes during development.

Where to next