docs
IntegrateErrors

Decline codes

Why a payment was declined, returned in `lastPaymentError.declineCode`: card decline codes and payment provider decline codes. 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 reason a payment was declined, normalized into XPay's vocabulary. It's set on every decline, for every payment method, in one of two families: card decline codes when a card issuer declines a card payment (lastPaymentError.code is card_declined), and payment provider decline codes when the provider of any other payment method, such as ValU or Fawry, declines it (lastPaymentError.code is payment_declined). For failures with no decline, such as processor errors or abandoned attempts, 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 payment provider declines, networkDeclineCode is the provider's own response code instead, and the provider defines its meaning; treat it the same way.

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_failed

The customer did not pass 3D Secure: a wrong or expired OTP, a cancelled challenge, or the issuer denied it. Nothing was charged. The customer can try again or use a different card.

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.

Payment provider decline codes

Payments made with a non-card payment method, such as ValU or Fawry, are declined with these codes, and lastPaymentError.code is payment_declined. Each code is the payment provider's reason for the decline. Codes that also appear in the card list carry the meaning below whenever code is payment_declined.

declineCodeMeaning
partner_generic_declineThe payment provider declined the payment without giving a reason.
invalid_customer_accountThe payment provider can't charge the customer's account (for example, it isn't registered, active, or eligible). If every payment with this method fails this way, contact XPay support.
payment_limit_exceededThe payment is over a limit on the customer's account with the provider, such as their available credit limit.
partner_high_risk_customerThe payment provider flagged the customer as high risk. Don't retry, and don't tell the customer the reason.
invalid_payment_informationThe provider rejected the payment details the customer used, such as a card number or PIN entered in the provider's own app.
lost_or_stolen_cardThe card the customer used with the provider was reported lost or stolen. Don't retry, and don't tell the customer the reason.
authentication_failedThe customer didn't complete the provider's verification, for example a wrong or expired one-time code.
insufficient_fundsThe customer has insufficient funds with the payment provider.
processing_errorThe payment provider had a processing error. Nothing was charged and retrying is safe.
currency_not_supportedThe payment provider doesn't support the payment's currency.
invalid_amountThe payment provider doesn't allow the payment's amount.
expired_cardThe card the customer used with the provider has expired.

A customer who cancels on the provider's page, or lets it expire, isn't declined: the attempt is abandoned and lastPaymentError.code is payment_abandoned. When the provider rejects the request itself or fails on its own side, nothing was declined either: declineCode is null and lastPaymentError.code is local_processor_rejected (retrying won't help, contact XPay support) or processor_error (retrying is safe).

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

On this page