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.
mit_not_supported_by_provider	configuration	acquirer	No provider your account routes to can process merchant-initiated card charges; every eligible channel was tried.
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_canceled	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.
amount_exceeds_remaining	technical	orchestrator	The requested amount is more than the referenced transaction has left to capture, void, or refund. Retrying elsewhere cannot help - lower the amount.
already_captured	technical	orchestrator	The authorization is already captured, so it cannot be captured or voided again. Nothing to retry - refund the captured amount instead.
already_refunded	technical	orchestrator	The captured amount is already fully refunded, so there is nothing left to refund. Nothing to retry - the money is already back.
not_captured	technical	orchestrator	The authorization was never captured, so there is nothing to refund. Void it to release the hold, or capture it first.
authorization_expired	technical	orchestrator	The authorization has expired, so it can no longer be captured or voided. Start a new payment.
authorization_closed	technical	orchestrator	The authorization is voided or declined, so it can no longer be captured, voided, or refunded. Start a new payment.

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.
provider_rejected_request	technical	merchant	The payment provider rejected the request data, for example a phone or name format it does not accept. Another provider may accept it, so the payment is routed onward. Check the data you sent.
transaction_not_found	technical	orchestrator	The provider holds no transaction under the given reference. Check the reference you sent rather than retrying.
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.