> For the complete documentation index, see [llms.txt](https://help.flycode.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.flycode.com/decline-codes-explained/what-decline-codes-tell-you.md).

# What Decline Codes Tell You

Decline codes are the issuing bank's reason for refusing a charge. Learn what they are, why they matter for subscription revenue, the difference between soft and hard declines, and how decline pattern

A decline code is the reason the issuing bank gives for refusing a card charge. Stripe and other processors surface it on every failed payment, and it is the most important input for deciding whether a failed subscription payment can be recovered automatically or needs the customer's help. This page answers the four questions merchants ask most about what decline codes mean.

## What are decline codes in the context of failed payments?

Decline codes are short strings returned by the card-issuing bank and surfaced by Stripe and other payment processors to explain why a transaction was refused, for example `insufficient_funds` or `do_not_honor`. The bank makes the approve or decline decision, sends a two-character network response code (such as `51` or `05`) back through the card network, and the processor translates it into its own readable code. In Stripe the value appears as `decline_code` inside the last payment error on a PaymentIntent, Charge or Invoice.

The code guides the merchant's next move: retry the same card later, request a new card, or tell the customer to contact their bank. Without it, every failed payment looks the same and gets the same treatment, which is why most legacy dunning underperforms.

## Why do decline codes matter for my subscription business?

Because they let you automate the right next step for each failure instead of guessing. Knowing whether a decline is soft or hard tells you whether to run optimized retries (soft declines) or prompt the customer for new payment details (hard declines). Getting this right saves revenue twice over: soft declines get recovered silently before the customer ever hears about a problem, and hard declines get an immediate, specific request instead of days of wasted retries.

For a subscription business, failed payments typically represent 8 to 15 percent of charges, and involuntary churn from those failures is often the largest single churn source. Decline codes are the lever that turns that loss into a recoverable, measurable number. See [Understanding Involuntary Churn](https://help.flycode.com/understanding-involuntary-churn) for the business impact.

## What's the difference between a soft and a hard decline?

A soft decline is temporary and can succeed on a later attempt; a hard decline is permanent for that card and requires new payment details.

|                                | Soft decline                                                                                                           | Hard decline                                                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Nature                         | Temporary condition at the issuer or account                                                                           | Card is invalid, closed, lost or stolen                                                                           |
| Typical codes                  | `insufficient_funds`, `generic_decline`, `do_not_honor`, `try_again_later`, `issuer_not_available`, `processing_error` | `lost_card`, `stolen_card`, `pickup_card`, `invalid_account`, `invalid_number`, `invalid_cvc`, `do_not_try_again` |
| Share of subscription failures | Roughly 60 to 70 percent                                                                                               | Roughly 30 to 40 percent                                                                                          |
| Right response                 | Retry with optimized timing, no customer contact needed at first                                                       | Stop retrying, request a new payment method, or fall back to a backup card on file                                |
| Recovery potential             | High with correct timing                                                                                               | Depends on outreach and backup methods                                                                            |

The rule that follows from this table: exhaust intelligent retries on soft declines before contacting the customer, and contact the customer immediately on hard declines.

## Are decline-code patterns useful for fraud detection?

Yes. Clusters of hard declines such as `stolen_card` or `pickup_card` on a single account or in a short window are a signal to add verification, and rapid repeats of soft declines across many small charges often indicate card-testing bots probing stolen numbers. Codes like `fraudulent` and `security_violation` come directly from the issuer's or Stripe Radar's risk scoring.

FlyCode surfaces these anomalies in its dashboard so payments and finance teams can distinguish a customer who is temporarily short of funds from an account that should be blocked, and it never retries a charge the issuer has flagged as fraud.

## Related

* [Where to Find Decline Codes (and How to Use Them)](https://help.flycode.com/decline-codes-explained/where-to-find-decline-codes-and-how-to-use-them)
* [How to Handle the Most Common Declines](https://help.flycode.com/decline-codes-explained/how-to-handle-the-most-common-declines)
* [Stripe decline codes reference on flycode.com](https://www.flycode.com/stripe/decline-codes)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.flycode.com/decline-codes-explained/what-decline-codes-tell-you.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.