Decline Categories
How LostChurn classifies payment decline codes into four categories that drive recovery strategy.
Every payment processor returns a decline code when a charge fails. LostChurn maps these raw codes to one of four standardized categories that determine how recovery proceeds. This classification happens automatically when a failed payment webhook is received.
The Four Categories
If a code is not in the mapping, it is classified as Unknown and treated like Hard Customer.
Soft Retry
Soft Retry declines are temporary issues that are likely to resolve without customer intervention. LostChurn will automatically retry these payments using smart retry timing.
Recovery outlook: High. 30-40% of Soft Retry declines are recovered through silent retries alone.
Subcategories
| Subcategory | Description | Example Codes | Typical Cooldown |
|---|---|---|---|
| Balance | Customer has insufficient funds but is expected to replenish | insufficient_funds | 48 hours |
| Issuer Temporary | The issuing bank's systems are temporarily unavailable | processing_error, try_again_later, issuer_not_available | 12-24 hours |
| Rate Limit | Too many transactions in a short period triggered a velocity check | card_velocity_exceeded, withdrawal_count_limit_exceeded | 72 hours |
| Generic | Issuer declined without giving a specific reason | generic_decline, do_not_honor | 48 hours |
Common Soft Retry Decline Codes
| Decline Code | Description | Max Retries | Cooldown |
|---|---|---|---|
insufficient_funds | Insufficient funds in account | 4 | 48h |
processing_error | Processing error at issuer | 3 | 24h |
try_again_later | Issuer temporarily unable to process | 3 | 12h |
card_velocity_exceeded | Too many transactions on card | 2 | 72h |
generic_decline | Generic decline, no specific reason | 3 | 48h |
do_not_honor | Issuer declined without specific reason | 3 | 48h |
issuer_not_available | Issuer system temporarily unavailable | 3 | 12h |
reenter_transaction | Issuer requests re-entry of transaction | 2 | 6h |
withdrawal_count_limit_exceeded | Exceeded withdrawal count limit | 2 | 72h |
Hard Customer
Hard Customer declines require the customer to take action -- updating their card details, contacting their bank, or completing authentication. LostChurn skips silent retries for these codes and immediately triggers dunning campaigns.
Recovery outlook: Moderate. Recovery depends on how quickly the customer responds to dunning messages.
Subcategories
| Subcategory | Description | Example Codes |
|---|---|---|
| Card Expired | Card has passed its expiration date | expired_card |
| Card Data | Incorrect card details were provided | incorrect_cvc, incorrect_number, invalid_cvc, invalid_number |
| SCA / 3D Secure | Strong Customer Authentication is required | authentication_required |
| Verification | Customer must verify identity with issuer | approve_with_id, call_issuer |
| Card Type | Card does not support this transaction type | card_not_supported, currency_not_supported |
| Issuer Block | Issuer has blocked the transaction | do_not_try_again, restricted_card, stop_payment_order |
| Card Updated | Card has been renewed with new details | new_account_information_available |
| Security | Security violation detected by issuer | security_violation |
| Generic | Issuer could not process for unspecified reason | no_action_taken |
Common Hard Customer Decline Codes
| Decline Code | Description | Customer Action Required |
|---|---|---|
expired_card | Card has expired | Update payment method |
incorrect_cvc | CVC number is incorrect | Re-enter card details |
incorrect_number | Card number is incorrect | Re-enter card details |
authentication_required | 3D Secure authentication required | Complete authentication |
call_issuer | Customer must contact card issuer | Contact bank |
card_not_supported | Card does not support this purchase type | Use a different card |
do_not_try_again | Issuer has permanently blocked this transaction | Contact bank or update card |
new_account_information_available | Card has been renewed | Update payment method |
restricted_card | Card has been restricted by issuer | Contact bank |
stop_payment_order | Cardholder requested stop on payment | Contact merchant |
Terminal
Terminal declines are permanent failures. The payment cannot be recovered through retries or customer action. LostChurn immediately marks these as terminal and stops all recovery activity.
Recovery outlook: None. Do not retry.
Subcategories
| Subcategory | Description | Example Codes |
|---|---|---|
| Fraud | Suspected or confirmed fraudulent activity | fraudulent, merchant_blacklist, stolen_card, lost_card, pickup_card |
| Closed Account | The account has been closed or invalidated | invalid_account |
| Test | Test-mode decline code used in development | testmode_decline |
Common Terminal Decline Codes
| Decline Code | Description | Why It's Terminal |
|---|---|---|
fraudulent | Payment flagged as fraudulent | Fraud risk -- do not retry |
merchant_blacklist | Card is on fraud blacklist | Blocked permanently |
stolen_card | Card reported stolen | Card is deactivated |
lost_card | Card reported lost | Card is deactivated |
pickup_card | Card ordered confiscated by issuer | Card is deactivated |
invalid_account | Account is invalid or closed | No account to charge |
testmode_decline | Test mode decline code | Not a real transaction |
Never retry Terminal declines. Attempting to charge a card flagged as stolen or fraudulent can result in fines from the card network and damage your merchant account standing.
Unknown
When LostChurn encounters a decline code that is not in its mapping table, it classifies it as Unknown. Unknown declines are treated like Hard Customer declines -- the system escalates to dunning communication rather than attempting silent retries.
This conservative approach ensures that unmapped codes do not result in wasted retry attempts or, worse, retries on codes that should not be retried.
LostChurn ships with 210+ mapped decline codes across all supported payment processors. The mapping table is updated regularly as new codes are encountered.
Dual Taxonomy: Classification vs Recovery
LostChurn uses two complementary layers to handle decline codes. Understanding the distinction helps when reading analytics dashboards and configuring recovery rules.
Classification Buckets (Why It Failed)
Classification buckets describe the cause of the payment failure:
| Bucket | Description |
|---|---|
| Card Error | Problem with the card itself -- expired, invalid number, incorrect CVC |
| Bank Error | The issuing bank declined the transaction -- insufficient funds, issuer unavailable |
| Network | Infrastructure or processing issue -- timeout, rate limit, gateway error |
| Fraud | Suspected or confirmed fraudulent activity flagged by the issuer or card network |
Recovery Categories (What LostChurn Does)
Recovery categories describe the action LostChurn takes in response:
| Category | Action |
|---|---|
| Soft Retry | Silent automatic retry at optimized timing |
| Hard Customer | Dunning campaign prompting the customer to act |
| Terminal | Mark as unrecoverable, stop all retries |
| Unknown | Treat as Hard Customer (conservative default) |
How They Map Together
Each classification bucket can map to one or more recovery categories depending on the specific decline code:
| Classification Bucket | Typical Recovery Categories |
|---|---|
| Card Error | Hard Customer (update card), Terminal (card deactivated) |
| Bank Error | Soft Retry (temporary), Hard Customer (contact bank) |
| Network | Soft Retry (transient issues resolve on their own) |
| Fraud | Terminal (never retry fraudulent charges) |
The classification buckets appear in the Decline Intelligence analytics view, while recovery categories drive the actual retry and outreach behavior described on this page.
Multi-PSP Support
LostChurn maintains separate decline code mappings for each supported payment processor. The same logical decline (e.g., "insufficient funds") may have different raw codes depending on the PSP:
| Provider | Insufficient Funds Code |
|---|---|
| Stripe | insufficient_funds |
| Braintree | 2001 |
| Adyen | Declined (with refusalReasonCode) |
| PayPal | INSTRUMENT_DECLINED |
Regardless of the PSP, LostChurn normalizes these into the same four categories so that your retry strategies and campaigns work consistently across providers.
Next Steps
- Retry Strategies -- how LostChurn uses decline categories to time retries
- Recovery States -- follow the full recovery lifecycle
- How Recovery Works -- overview of the recovery pipeline