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
51from 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
networkDeclineCodeinto 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.
declineCode | Meaning |
|---|---|
partner_generic_decline | The payment provider declined the payment without giving a reason. |
invalid_customer_account | The 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_exceeded | The payment is over a limit on the customer's account with the provider, such as their available credit limit. |
partner_high_risk_customer | The payment provider flagged the customer as high risk. Don't retry, and don't tell the customer the reason. |
invalid_payment_information | The 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_card | The card the customer used with the provider was reported lost or stolen. Don't retry, and don't tell the customer the reason. |
authentication_failed | The customer didn't complete the provider's verification, for example a wrong or expired one-time code. |
insufficient_funds | The customer has insufficient funds with the payment provider. |
processing_error | The payment provider had a processing error. Nothing was charged and retrying is safe. |
currency_not_supported | The payment provider doesn't support the payment's currency. |
invalid_amount | The payment provider doesn't allow the payment's amount. |
expired_card | The 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
Payment error codes
The other reference for failed payments: lastPaymentError.code values.
Payment errors
The model: how lastPaymentError is shaped, plus the adviceCode-driven handler pattern.
API error codes
The reference for errors returned in HTTP responses to your API calls.
API errors
The synchronous error envelope.
Errors introduction
Back to the top. The two-surfaces map.
Payment error codes
Every value of `lastPaymentError.code`, grouped by what happened. Each entry's URL is the value of `lastPaymentError.docUrl`.
Introduction
The Workbench is a slide-up drawer that lives in the dashboard. Inspect resources, watch events, read logs, and check health without leaving the page.