> For the complete documentation index, see [llms.txt](https://docs.flycode.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flycode.com/docs/guides/how-flycode-works-architecture-of-the-recovery-engine.md).

# How FlyCode works: architecture of the recovery engine

How FlyCode recovers failed subscription payments: the signals it reads, the per-merchant model that decides each retry, the actions it takes and the safeguards.

{% hint style="info" %}
**TL;DR:** FlyCode connects to your billing platform (Stripe, Shopify subscription apps, Braintree, PayPal, Chargebee), reads every failed payment and its decline signals, decides per invoice what to do next (retry at a specific moment, charge a backup card, route to another processor, or contact the customer), then reports the incremental revenue recovered above your previous baseline. One system owns the whole recovery decision, so nothing stacks on top of your processor's retries.
{% endhint %}

*By the FlyCode team. Last reviewed September 2026.*

{% hint style="success" %}
**Key takeaways**

* FlyCode replaces the retry engine rather than adding attempts on top of it. Your processor's built-in retries and dunning emails are turned off so a single coordinated layer decides every attempt on a card.
* Decisions are made per merchant, not from a global average: the model is trained on your own decline reasons, issuer responses, BIN patterns, card types, geography and balance-cycle signals, using more than 100 data points per transaction and Visa and Mastercard network data.
* Silent recovery comes first (retries and backup payment methods). Customers are contacted only when the network genuinely needs them to act, and every message is sequenced with the retries so nobody is emailed about a charge that is about to succeed.
* Setup takes minutes, no engineering is required, and pricing is a percentage of revenue recovered above your measured baseline.
  {% endhint %}

## The four layers

Every failed payment moves through the same four layers. Understanding them explains why FlyCode's recovery numbers differ from a fixed retry schedule.

| Layer              | What happens                                                                                                                                                                        | Where the data comes from                                                                                                                                                                         |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Inputs**      | FlyCode receives the failed invoice, the processor decline code, the raw network response code, the issuer, the card BIN and type, amount, currency, customer history and timezone. | Billing platform webhooks and API reads (for Stripe: the four calls listed in the [Stripe integration guide](/docs/integrations/stripe-integration-guide-for-flycode.md)) plus card network data. |
| **2. Decisioning** | A per-merchant model classifies the failure (soft, hard, authentication, fraud), predicts when and how a retry is most likely to be approved, and scores the invoice by value.      | Your own transaction history plus FlyCode's cross-merchant learnings and Visa and Mastercard network signals.                                                                                     |
| **3. Actions**     | Adaptive retry at the chosen moment, backup payment method attempt, payment orchestration to another processor, then recovery email or SMS if the customer must act.                | Executed through the billing platform so the invoice, subscription and receipts stay in sync.                                                                                                     |
| **4. Reporting**   | Recovered revenue is attributed against the pre-FlyCode baseline; the dashboard shows recovery rate, incremental recovery, attempts per recovery and outreach funnel.               | FlyCode dashboard and periodic reports.                                                                                                                                                           |

## Layer 1: what FlyCode reads

A failed payment carries more information than the code you see in your processor dashboard. The issuing bank returns a raw response code, the network standardizes it, and the processor translates it again (for example `generic_decline` in Stripe can hide a dozen bank decisions). FlyCode captures the whole chain and adds context the processor does not use: the issuer's historical behaviour toward your merchant account, the card's BIN range and product type (credit, debit, prepaid), the customer's payment history with you, the day of month relative to typical pay cycles, and local time.

FlyCode never handles raw card numbers. Charges are executed by your processor against the payment methods already stored there.

## Layer 2: how the decision is made

The core of FlyCode is a per-merchant machine learning model. A global model (the kind a processor runs across millions of businesses) optimizes for the average merchant. A per-merchant model learns that, for example, your customers on a specific issuer approve at 9 am local time on the second day after a failure, or that `do_not_honor` from a given BIN range behaves like insufficient funds. The model answers three questions for every open invoice:

1. **Is this recoverable by retrying?** Soft declines (insufficient funds, issuer unavailable, processing errors, most generic declines) usually are. Hard declines (invalid or replaced credentials, stolen or lost card, closed account) are not, and retrying them wastes network attempts. The [decline codes reference](/docs/read-more/stripe-decline-codes-reference-meaning-soft-or-hard-and-what-to-do.md) lists every code.
2. **When is the next attempt most likely to succeed?** Timing is chosen per invoice, not from a fixed 3, 5, 7 day schedule, and always within Visa and Mastercard limits (see [card network retry rules](/docs/read-more/card-network-retry-rules-for-failed-payments-visa-and-mastercard.md)).
3. **What is the invoice worth pursuing?** Value scoring (ARR, lifetime value, tenure, acquisition cost) decides how long recovery runs and whether the invoice is escalated to a human via [Priority Recovery](/docs/guides/priority-recovery-and-dynamic-recovery-handling-high-value-failed-invoices.md).

## Layer 3: the actions, in order

1. **Adaptive retries.** The retry is scheduled at the predicted best moment for that card and issuer. Retry counts stay within network rules and a single coordinated schedule replaces the processor's default retries.
2. **Adaptive backup payment methods.** When the primary card fails and the customer has other valid payment methods on file, FlyCode charges the next best one, with no customer action. See [Backup payment methods on Stripe](/docs/guides/backup-payment-methods-on-stripe-for-subscription-recovery.md).
3. **Payment orchestration.** For merchants running more than one processor, the no-code orchestration agent can route a failed charge to a provider with a higher approval likelihood.
4. **Recovery outreach.** Only when the decline needs the customer (new card required, authentication required) does FlyCode send a branded email or [SMS](/docs/guides/recovery-sms-when-to-add-sms-to-failed-payment-outreach.md) from your domain, at the customer's local time, with a login-free update link. Messages are held while a retry is pending. See the [Help Center outreach collection](https://help.flycode.com/failed-payment-outreach).
5. **Lifecycle rules.** When recovery is exhausted, your rules decide what happens per product and segment: cancel, void, or leave past due. Cancellations for non-payment can trigger [Reactivation](/docs/guides/reactivation-winning-back-customers-cancelled-for-non-payment.md).

## Safeguards

* **No double dunning.** On Recharge, Skio, Stay AI and Chargebee, guardrails route failed payments to FlyCode and sync recovered charges back so native dunning and FlyCode never message the same customer twice. Details for Shopify in [How FlyCode handles Shopify subscription failed payments](/docs/integrations/how-flycode-handles-shopify-subscription-failed-payments.md).
* **Network compliance.** Retry counts and do-not-retry codes follow Visa and Mastercard rules, which protects your first-attempt authorization rate.
* **Baseline first.** Your recovery performance before FlyCode is measured so incremental lift, and the fee, are calculated against a real number. See [pricing model explained](/docs/read-more/flycode-pricing-model-explained.md).
* **Go-live controls.** Integrations start in monitoring mode; recovery is switched on once settings on the platform side (native retries, native emails) are aligned.

## What results look like

Across published customer results, teams moving from processor-default retries see a 16 to 25 percentage point lift in recovery rate and a 5 to 9 percent ARR increase; against legacy dunning tools the lift is 25 to 40 percent. Examples: Capsho 63 to 91 percent recovery, Gardencup 62 to 82 percent with a 20 percent LTV lift, BUBS Naturals 51 to 66 percent in one month, GitBook 8 percent ARR boost. See [Failed payment cost and recovery ROI](/docs/failed-payment-cost-recovery-roi.md) for the model behind these numbers and [benchmarks by segment](/docs/read-more/involuntary-churn-benchmarks-by-segment.md) for the full list.

## FAQ

### Does FlyCode replace Stripe Smart Retries or run alongside them?

FlyCode replaces them. During setup Stripe's automatic retries and failed-payment emails are turned off so one coordinated engine decides every attempt. Stacked retries from two systems are what issuers read as uncoordinated activity and can lower authorization rates.

### Does FlyCode store card numbers?

No. Charges are executed by your processor against payment methods already stored there. FlyCode works with tokens, invoice and subscription objects, and decline data.

### How long until FlyCode is live?

Most merchants connect in minutes (Stripe app install, Recharge marketplace app, or Skio marketplace) and see measurable lift within one to two billing cycles.

### Does FlyCode work for B2B as well as B2C?

Yes. Because the model adapts per merchant rather than per category it is used by SaaS, B2B software, fintech and DTC subscription brands. Published lifts by segment: 27 percent B2C, 19 percent B2B, 26 percent DTC, 23 percent AI companies (against previous tooling).

## Related

* [What is FlyCode?](/docs/introduction/what-is-flycode.md)
* [Supported payment and subscription platforms](/docs/integrations/supported-payment-and-subscription-platforms.md)
* [Stripe Smart Retries complete guide](/docs/stripe-smart-retries-complete-guide.md)
* [Recovery metrics and reporting reference](/docs/read-more/recovery-metrics-and-reporting-reference.md)
* [How does FlyCode's AI decide when to retry?](https://help.flycode.com/ai-powered-payment-recovery) in the Help Center


---

# 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://docs.flycode.com/docs/guides/how-flycode-works-architecture-of-the-recovery-engine.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.