Decline codes

When a payment is declined rather than rejected for a request-level error, the transaction carries a normalized decline code that describes why. Provider integrations map their raw acquirer/issuer result codes onto this single, provider-agnostic vocabulary, so you get one stable set of codes regardless of which processor handled the payment.

Decline codes are distinct from the API error codes: an error code means the request could not be accepted (validation, auth, conflicts), while a decline code means the request was accepted and attempted but the payment did not succeed. There is one deliberate exception — a handful of errors surface a decline code as the envelope's code; see Decline codes in the error envelope.

Where you see them

Only decline_code is on the Transaction resource. The classification attributes around it are delivered on the payment webhook payload — if you are reconciling from the API rather than the webhook, they will not be there.

Field	Type	Transaction	Webhook	Description
decline_code	string	✅	✅	The canonical decline code (snake_case). Branch on this.
decline_category	string	—	✅	The kind of failure — a low-cardinality grouping over the codes. Says what went wrong.
decline_source	string	—	✅	The party or layer that originated the decline. Says who declined.
retry_advice	string	—	✅	The network's per-attempt retry verdict. Varies per attempt; authoritative when present.
retryable	boolean	—	✅	Whether the customer can retry on the same checkout session.

On a successful transaction they are all null or absent.

The transaction also carries the raw provider result alongside the normalized code — provider_error_code and provider_error_reason, plus network_error_code and network_error_reason when the provider relays the card network's own error. Those are verbatim, provider-specific, and unstable: log them for support, but branch on decline_code.

decline_category and decline_source are orthogonal: the same kind of failure can come from different parties. For example, insufficient_funds is category funds and source issuer.

Branch on decline_code, group on decline_category

Use decline_code for precise handling, and decline_category when you just need to react to a kind of failure (e.g. show a "check your card details" message for the whole instrument family) without enumerating every code.

Payment decline codes

The payment-domain taxonomy, covering instrument, issuer, authentication, risk, and payer failures.

Funds & limits

decline_code	Category	Source	Meaning
insufficient_funds	funds	issuer	The account or card has insufficient funds to complete the transaction.
amount_limit_exceeded	funds	acquirer	The transaction amount exceeds a limit on the account or payment method.
velocity_limit_exceeded	funds	issuer	The payment method has reached its transaction frequency limit.
invalid_amount	funds	orchestrator	The transaction amount is invalid for this payment method.

Card & instrument

decline_code	Category	Source	Meaning
expired_card	instrument	issuer	The card has expired.
invalid_card_number	instrument	customer	The card number is incorrect or invalid.
invalid_cvc	instrument	issuer	The card security code is incorrect.
invalid_expiry	instrument	customer	The card expiration date is incorrect.
incorrect_address	instrument	issuer	The billing address or postal code does not match the records of the issuer.
card_type_not_accepted	configuration	acquirer	The acquirer does not accept this card type, brand, or installment option.
currency_not_supported	configuration	acquirer	The payment method does not support the transaction currency.
multicapture_not_supported	configuration	acquirer	The provider did not grant multiple partial captures on this authorization. See Manual capture.
invalid_account	instrument	issuer	The account is invalid, closed, or does not exist.

Issuer decisions

decline_code	Category	Source	Meaning
generic_decline	decision	issuer	The payment was declined without a specific reason.
generic_decline_final	decision	issuer	The payment was declined with no actionable reason and should not be retried or re-routed.
transaction_not_permitted	eligibility	issuer	The issuer does not permit this type of transaction on this card.
authorization_revoked	decision	issuer	The cardholder revoked authorization or placed a stop-payment on this transaction.
card_blocked	instrument	issuer	The card is blocked, locked, or not yet activated.
card_lost_or_stolen	risk	issuer	The card has been reported lost or stolen.
contact_issuer	decision	issuer	The payment was declined and the customer needs to contact their bank.
issuer_unavailable	availability	issuer	The card issuer could not be reached to authorize the payment.

Authentication & verification

decline_code	Category	Source	Meaning
three_ds_required	authentication	issuer	The payment requires a 3-D Secure / strong customer authentication challenge.
pin_required	authentication	issuer	The card requires a PIN to be entered to complete the payment.
three_ds_failed	authentication	customer	3-D Secure / identity verification failed or was not completed.
incorrect_pin	authentication	customer	The PIN entered is incorrect.
verification_attempts_exceeded	authentication	issuer	The number of PIN or verification attempts has been exceeded.

Risk, fraud & compliance

decline_code	Category	Source	Meaning
fraud_suspected	risk	issuer	The payment was declined because fraud is suspected.
risk_blocked	risk	orchestrator	The payment was blocked by risk controls.
blocked_by_merchant	risk	merchant	The payment was blocked by the merchant's own block list.
compliance_violation	risk	orchestrator	The payment was declined for legal or compliance reasons.

Customer & payment method

decline_code	Category	Source	Meaning
payer_cancelled	cancellation	customer	The customer cancelled or abandoned the payment.
payer_ineligible	eligibility	customer	The customer cannot use this payment method (KYC, identity, age, or account status).
invalid_customer_details	instrument	customer	The customer's identification or personal details are invalid.
no_payment_method_available	eligibility	customer	No payment method is available for this customer on this channel.

Processing

decline_code	Category	Source	Meaning
duplicate_transaction	technical	orchestrator	A transaction with identical details was submitted recently.
nothing_to_settle	technical	orchestrator	The order moved no money, so there is nothing to capture or refund.

Platform decline codes

Generic failures that are not specific to any payment instrument or provider taxonomy — processing, availability, configuration, and request problems.

decline_code	Category	Source	Meaning
processing_error	technical	acquirer	An error occurred while processing the payment.
provider_unavailable	availability	network	The payment provider is temporarily unavailable.
provider_unreachable	availability	network	The payment provider could not be reached.
timeout	availability	network	The payment timed out before it could be completed.
configuration_error	configuration	merchant	The payment could not be processed due to a configuration problem.
authentication_failed	configuration	merchant	The payment provider rejected the channel credentials. This is your credentials failing at the provider, not the cardholder failing 3-D Secure — for that, see three_ds_failed.
merchant_not_eligible	eligibility	merchant	The merchant cannot accept this payment (compliance, status, or category).
invalid_request	technical	orchestrator	The payment request was invalid.
general_error	technical	orchestrator	The payment could not be completed due to an internal error.
unknown	technical	unknown	The payment failed for an unknown reason.

Categories

decline_category is a stable, low-cardinality grouping that says what kind of failure occurred. It is informational only — it does not drive routing.

decline_category	Meaning
funds	Balance, credit, or transaction-amount limits.
instrument	The payment instrument or its data (card number, expiry, CVC, account, customer details).
authentication	Strong customer authentication, 3-D Secure, or PIN.
risk	Fraud, risk controls, block lists, or compliance.
availability	A required party (issuer, provider, network) was unreachable or timed out.
configuration	Cannot be processed as set up — capability, support, or merchant/channel configuration mismatch.
eligibility	A party is not permitted or qualified — merchant or payer eligibility, transaction not permitted.
decision	A discretionary verdict (typically issuer do-not-honor) not reducible to a specific kind.
cancellation	The payer cancelled or abandoned the payment.
technical	Processing errors, malformed requests, deduplication, or unknown failures.

Sources

decline_source is the party or layer that originated the decline — the honest basis for whether re-routing to another channel could help.

decline_source	Meaning
issuer	The cardholder's bank / issuing institution declined or could not be reached.
acquirer	The acquiring side declined — capability, support, or account standing at the acquirer.
network	The scheme / connectivity layer between us and the acquirer or issuer (timeouts, reachability).
merchant	The merchant's configuration, account standing, or the merchant's own controls.
customer	The payer themself — cancellation, eligibility, identity, or no method available to them.
orchestrator	Orchestr — request validation, our configuration, our risk engine, or deduplication.
unknown	The source could not be determined.

Retry advice

retry_advice is the card network's per-attempt retry verdict, normalized across schemes (it folds in Mastercard Merchant Advice Codes and Visa advice). Unlike the category and source — which are fixed properties of the code — retry advice varies per attempt: the same code can arrive do_not_retry on one authorization and retry_later on the next. When present it is authoritative and overrides any default assumption you would make from the code alone.

retry_advice	Meaning
do_not_retry	The network instructs that this payment must not be retried.
retry_later	The payment may succeed if retried later.
update_card	The payment may succeed once the customer corrects or updates their card details.

When no advice was given — a non-card provider, or a card provider that returned none — the field is omitted from the payload entirely rather than sent as a "none" string. Treat absent as "no advice", and don't write a comparison against "none".

Handling declines

• Branch on decline_code, never on the message text — messages may change without notice.
• Honour retry_advice when it is present: do not re-attempt a do_not_retry, and prompt the customer to fix their card on update_card.
• Use decline_category for coarse, user-facing messaging when you don't want to map every code.
• decline_source of issuer generally means re-routing won't help; network or availability failures are the ones most likely to clear on a later retry.
• Refunds reuse the payment payload but never carry decline fields — they are always null.