API Reference
Decline Code Reference
Complete reference of payment decline codes across Stripe, Braintree, and generic processors — with categories, descriptions, and recommended actions.
This page provides a comprehensive reference of all decline codes that LostChurn maps across supported payment processors. Each code is classified into one of four decline categories that determine the recovery strategy.
Category Summary
| Category | Recovery Strategy | Expected Recovery Rate |
|---|---|---|
| Soft Retry | Silent automatic retries at optimized times | 30-40% |
| Hard Customer | Dunning campaigns prompting customer action | 10-20% |
| Terminal | No retry -- mark as unrecoverable | 0% |
| Unknown | Treated as Hard Customer (conservative default) | 10-15% |
Stripe Decline Codes
Soft Retry
| Code | Description | Subcategory | Max Retries | Cooldown |
|---|---|---|---|---|
insufficient_funds | Insufficient funds in the account | Balance | 4 | 48h |
processing_error | Processing error at the issuer | Issuer Temporary | 3 | 24h |
try_again_later | Issuer temporarily unable to process | Issuer Temporary | 3 | 12h |
card_velocity_exceeded | Too many transactions in short period | Rate Limit | 2 | 72h |
generic_decline | Declined without specific reason | Generic | 3 | 48h |
do_not_honor | Issuer declined without reason | Generic | 3 | 48h |
issuer_not_available | Issuer system temporarily unavailable | Issuer Temporary | 3 | 12h |
reenter_transaction | Issuer requests re-entry | Issuer Temporary | 2 | 6h |
withdrawal_count_limit_exceeded | Exceeded withdrawal count limit | Rate Limit | 2 | 72h |
service_not_allowed | Card type not accepted for service | Generic | 2 | 48h |
transaction_not_allowed | Transaction type not permitted | Generic | 2 | 48h |
not_permitted | Transaction not permitted to cardholder | Generic | 2 | 48h |
offline_pin_required | Offline PIN verification required | Issuer Temporary | 2 | 24h |
online_or_offline_pin_required | PIN verification required | Issuer Temporary | 2 | 24h |
no_action_taken | Issuer could not process | Generic | 2 | 48h |
revocation_of_all_authorizations | All authorizations revoked | Generic | 1 | 72h |
approve_with_id | Can be approved with identification | Generic | 2 | 24h |
Hard Customer
| Code | Description | Subcategory | Customer Action |
|---|---|---|---|
expired_card | Card has expired | Card Expired | Update payment method |
incorrect_cvc | CVC number is incorrect | Card Data | Re-enter card details |
incorrect_number | Card number is incorrect | Card Data | Re-enter card details |
incorrect_zip | ZIP/postal code is incorrect | Card Data | Re-enter card details |
invalid_cvc | CVC is invalid | Card Data | Re-enter card details |
invalid_number | Card number is invalid | Card Data | Re-enter card details |
invalid_expiry_month | Expiry month is invalid | Card Data | Re-enter card details |
invalid_expiry_year | Expiry year is invalid | Card Data | Re-enter card details |
authentication_required | 3D Secure authentication required | SCA / 3D Secure | Complete authentication |
call_issuer | Customer must contact card issuer | Verification | Contact bank |
card_not_supported | Card does not support this purchase type | Card Type | Use a different card |
currency_not_supported | Card does not support this currency | Card Type | Use a different card |
do_not_try_again | Issuer has permanently blocked transaction | Issuer Block | Contact bank or update card |
new_account_information_available | Card renewed with new details | Card Updated | Update payment method |
restricted_card | Card restricted by issuer | Issuer Block | Contact bank |
stop_payment_order | Cardholder requested stop on payment | Issuer Block | Contact merchant |
security_violation | Security violation detected | Security | Contact bank |
card_declined | General card decline | Generic | Contact bank or update card |
invalid_account | Account is invalid | Generic | Update payment method |
live_mode_test_card | Test card used in live mode | Card Data | Use a real card |
pin_try_exceeded | PIN entry attempts exceeded | Security | Contact bank |
testmode_decline | Decline in test mode | Card Data | Use test-approved card |
Terminal
| Code | Description | Subcategory | Why Terminal |
|---|---|---|---|
fraudulent | Suspected fraud | Fraud | Fraud risk -- never retry |
merchant_blacklist | Card on merchant fraud blacklist | Fraud | Permanently blocked |
stolen_card | Card reported stolen | Fraud | Card deactivated |
lost_card | Card reported lost | Fraud | Card deactivated |
pickup_card | Card ordered confiscated by issuer | Fraud | Card deactivated |
revocation_of_authorization | Authorization permanently revoked | Closed Account | Cannot charge |
Never retry Terminal decline codes. Repeated attempts on cards flagged as stolen or fraudulent can result in fines from card networks and may jeopardize your merchant account.
Braintree Decline Codes
Braintree uses numeric processor response codes. LostChurn maps these to the same four categories.
Soft Retry
| Code | Description | Subcategory | Max Retries | Cooldown |
|---|---|---|---|---|
2001 | Insufficient funds | Balance | 4 | 48h |
2002 | Limit exceeded | Rate Limit | 2 | 72h |
2003 | Cardholder activity limit exceeded | Rate Limit | 2 | 72h |
2038 | Processor declined | Issuer Temporary | 3 | 24h |
2046 | Declined | Generic | 3 | 48h |
2047 | Call issuer -- general decline | Generic | 3 | 48h |
2053 | Card reported as lost or stolen (soft) | Generic | 1 | 72h |
2057 | Issuer or cardholder restriction | Generic | 2 | 48h |
2059 | Contact issuer | Generic | 2 | 48h |
2099 | General processor error | Issuer Temporary | 3 | 12h |
Hard Customer
| Code | Description | Subcategory | Customer Action |
|---|---|---|---|
2004 | Expired card | Card Expired | Update payment method |
2005 | Invalid credit card number | Card Data | Re-enter card details |
2006 | Invalid expiration date | Card Data | Re-enter card details |
2010 | Card issuer declined CVV | Card Data | Re-enter card details |
2014 | Card type not accepted | Card Type | Use a different card |
2024 | Card type not enabled | Card Type | Use a different card |
2044 | Decline -- CVV2/CID failure | Card Data | Re-enter card details |
2048 | Invalid amount | Generic | Contact merchant |
2051 | Insufficient funds (hard) | Generic | Add funds or use different card |
2074 | Funding source funding failed | Generic | Update funding source |
2075 | PayPal business account restricted | Generic | Contact PayPal |
Terminal
| Code | Description | Subcategory | Why Terminal |
|---|---|---|---|
2000 | Do not honor | Fraud | General permanent decline |
2007 | No account | Closed Account | Account does not exist |
2009 | No such issuer | Closed Account | Invalid routing |
2015 | Transaction not allowed | Fraud | Permanently blocked |
2041 | Declined -- fraud detected | Fraud | Fraud risk |
2043 | Fraud detected -- card reported lost/stolen | Fraud | Card deactivated |
2060 | Contact gateway | Closed Account | Gateway-level block |
2062 | Invalid gateway configuration | Closed Account | Configuration issue |
Generic Decline Codes
For payment processors not explicitly mapped, LostChurn uses a generic mapping based on common decline patterns.
Soft Retry
| Pattern | Description | Subcategory |
|---|---|---|
insufficient_funds | Insufficient funds | Balance |
temporary_failure | Temporary processing failure | Issuer Temporary |
rate_limited | Rate limit exceeded | Rate Limit |
try_again | Retry suggested | Issuer Temporary |
processing_error | General processing error | Issuer Temporary |
issuer_unavailable | Issuer system down | Issuer Temporary |
Hard Customer
| Pattern | Description | Subcategory |
|---|---|---|
expired | Card or account expired | Card Expired |
invalid_card | Card details invalid | Card Data |
invalid_cvc | CVC/CVV invalid | Card Data |
authentication_required | Authentication needed | SCA / 3D Secure |
card_not_supported | Card type not accepted | Card Type |
restricted | Card or account restricted | Issuer Block |
contact_issuer | Customer must contact bank | Verification |
Terminal
| Pattern | Description | Subcategory |
|---|---|---|
fraud | Fraud detected | Fraud |
stolen | Card reported stolen | Fraud |
lost | Card reported lost | Fraud |
blacklisted | Card blacklisted | Fraud |
account_closed | Account permanently closed | Closed Account |
How LostChurn Uses Decline Codes
When a failed payment webhook arrives, LostChurn:
- Extracts the raw decline code from the webhook payload.
- Looks up the code in the PSP-specific mapping table.
- Assigns a category and subcategory that determine the recovery strategy.
- Sets retry parameters (max retries, cooldown period) based on the subcategory.
- Routes to the appropriate handler -- silent retries for Soft Retry, dunning campaigns for Hard Customer, or immediate terminal marking.
If a code is not found in the mapping table, it defaults to Unknown and is treated as Hard Customer to avoid retrying codes that should not be retried.
LostChurn's decline code mapping is updated regularly as payment processors introduce new codes. If you encounter an unmapped code, it will be classified as Unknown until the mapping is updated. You can report unmapped codes to support@lostchurn.com to expedite mapping.
Querying Decline Codes via API
You can filter payments by decline code or category using the Payments API:
# All payments with insufficient_funds decline
curl "https://api.lostchurn.com/v1/payments?decline_code=insufficient_funds" \
-H "Authorization: Bearer lc_live_your_api_key"
# All payments in the soft_retry category
curl "https://api.lostchurn.com/v1/payments?decline_category=soft_retry" \
-H "Authorization: Bearer lc_live_your_api_key"Next Steps
- Decline Categories -- how categories drive recovery strategy
- Payments API -- query payments by decline code
- How Recovery Works -- the full recovery pipeline