FlyCode's app for Stripe - failed payments recovery
Maximize Subscription Revenue and increase retention with failed payment AI & Payment optimization
Last updated
Maximize Subscription Revenue and increase retention with failed payment AI & Payment optimization
Last updated
2025 FlyCode © All Right Reserved
The Verified Stripe App from FlyCode seamlessly integrates with Stripe Billing, eliminating the need for custom implementation work to recover failed subscription payments.
With FlyCode's AI/ML recovery engine, you can optimize payment retries and reduce churn if you manage your subscriptions through Stripe Billing.
Installation is straightforward: Simply install the FlyCode App from the Stripe Marketplace. After installation, configure your Revenue Recovery settings within your Stripe portal as described in the Going Live Guide and activate your App. Afterwards, FlyCode works automatically in the background without any further implementation.
The FlyCode app connects your Stripe account to FlyCode's AI/ML-powered recovery engine. It uses Stripe Webhooks to monitor subscription events, relays relevant data to FlyCode's recovery engine, and executes actions via the Stripe API to trigger payment retries and other subscription management steps. This is all transparently executed and reflected on your Stripe dashboard as will be explained below.
1. Stripe Webhook Events
The FlyCode app subscribes to specific Stripe webhook events relevant to payments recovery and subscription management. These events provide real-time updates about your customer subscriptions and payments and are essential for providing the FlyCode recovery engine with real-time data and identifying the best timing for payment retries. The FlyCode app is designed to not interfere with your existing webhook configurations from other apps or API integrations.
2. Stripe API Usage
The FlyCode app utilizes the Stripe API to perform specific actions based on the recovery strategy set out by FlyCode's AI/ML recovery engine.
2.1 Marking Failed Subscription Invoices
For transparency and analytics purposes, the FlyCode app annotates failed subscription invoices that enter the recovery flow. The app uses the Update Invoice API call to add a specific key and value within the metadata object. This identifies invoices being managed by the FlyCode recovery engine. Stripe UI:
You'll see this metadata displayed in two ways within the Stripe dashboard:
Invoice Page UI: The flycode_recovery:true metadata field will be visible within the invoice details.
API Logs: The Update Invoice API call will be recorded in the invoice's event logs, showing the specific update executed by the FlyCode app.
2.2 Retrying Failed Invoices
When FlyCode's AI/ML engine determines that a specific invoice should be retried, an internal event is triggered within the FlyCode app. This initiates an Invoice Pay API call to attempt payment of the previously failed invoice.
Stripe UI:
Invoice Page UI: The Invoice Pay API calls will be logged in the Invoice Recent Activity view, at the top of Invoice page.
2.3 Subscription Management & Invoice Status Updates
When the recovery process reaches the maximum number of retries for a specific invoice without a successful payment, the FlyCode app takes the following optional but recommended actions:
Subsequent Invoice Handling: All open (unpaid) invoices created after the original unrecoverable invoice under the same subscription will also be marked as "void" or "uncollectible" using the corresponding API call.
Safeguard Mechanism:
To ensure that active subscriptions are not accidentally canceled, the FlyCode App includes a safeguard mechanism:
If any new invoices created after the original uncollectible invoice have been successfully paid, the subscription will not be canceled. This prevents the cancellation of subscriptions that have become healthy through other means.
Good Practice:
As mentioned above, the subscription cancellation step, as well as the invoice status cleanup workflows, are enabled by the FlyCode app by default but are not required. While the app can function without these actions, we strongly recommend utilizing them to prevent further payment attempts on these invoices, ensure that subscription and invoice statuses accurately reflect payment outcomes, thus minimizing customer and merchant confusion.
Summary
These actions represent the only write [POST] Stripe API calls performed by the FlyCode App. As with all Stripe API interactions, each call is logged in the Stripe developer portal and reflected in the Stripe UI under the relevant objects, providing full transparency. Furthermore, to prevent any payment duplications or status misalignments caused by race conditions, or other edge cases, the FlyCode app always checks the current status of the relevant Stripe object before executing an action triggered by the FlyCode's AI/ML engine. This ensures idempotency and that actions are only performed when truly necessary.
3. Dunning Notifications
For optimal results and a consistent brand experience, we recommend disabling Stripe's default email recovery notifications and instead leveraging FlyCode’s Dunning Notifications service.
FlyCode’s Dunning Notifications service provides several key benefits:
Optimal Timing: Notifications are timed and triggered by FlyCode’s AI/ML engine, ensuring that messages are sent in sync with the payment retry schedule for maximal impact.
Enhanced Customer Experience: Send email notifications from your own domain (higher trust and delivery rates), using your unique marketing and brand language.
Translated to higher recovery rates through better customer experiences and optimal retry timing.
For detailed guidance on disabling Stripe's default emails, please refer to the Going Live Guide.
The following manual changes from Stripe’s Revenue Recovery Settings section should be done before activating FlyCode App. Please make the change based on the order of the instructions below:
Retries Setting
To be configured from here. Follow these steps in this order to configure your retries settings:
Emails Setting
To be configured from here. Follow these steps to configure your payment-related email settings:
Stripe Recovery Emails: If you are using FlyCode's Dunning Notifications (recommended), disable Stripe's default payment recovery emails to avoid duplicate notifications to your customers.
After launching the FlyCode App, you can monitor its performance and impact directly from your Stripe portal.
Key Considerations:
AI/ML Optimization: The FlyCode AI/ML engine typically requires 6-8 weeks to optimize its models for your specific merchant-customer dynamics.
Go Back in Time Feature: FlyCode's "Go Back in Time" feature revisits previously failed invoices (typically up to 60 days prior to FlyCode activation). This can lead to changes in the recovery rates of previous months as previously unrecoverable invoices might be recovered.
Need help? Email us or get started
Successful Retry: If the retry is successful, Stripe automatically changes the invoice status to "paid". In most cases, this will also change the subscription status to "active", provided there are no other outstanding issues with the subscription.
Unsuccessful Retry: The payment attempt will be logged in the Invoice Recent Activity view, and Stripe will also add the defaulted next planned retry (this is not the FlyCode next scheduled retry).
API Logs: The Invoice Pay API call will be also recorded in the invoice's event logs, showing the specific retry event triggered by the FlyCode app.
Payment Intents and Charges: From the perspective of payment intents and charges, the existing Stripe behavior remains unchanged. A Pay Invoice call translated by Stripe to a new charge under the original payment intent connected to the invoice being recovered. Therefore, no additional payments will be added under the invoice.
Subscription Cancellation: The app uses the Cancel Subscription API call to cancel the subscription associated with the unrecoverable invoice. In the Stripe UI, the subscription will be displayed as canceled, with the cancellation event log. The app can also optionally include cancellation details using the cancellation_details property, which will be visible in the UI as well.
Invoice Status Updates: Depending on the merchant's internal billing preferences, the app uses either the Void an Invoice or Mark an Invoice as Uncollectible API calls to to set the original unrecovered invoice status accordingly.
Subscription and Invoice Status: Set the subscription and invoice status upon failed recovery to "leave as past-due." This ensures that the FlyCode App can manage the post recovery statuses effectively without interference from Stripe's default behaviors.
Card Retries: In the "Card retries" section, select the "custom" option. Configure the custom retries to a maximum period of 7 days, using 3 retries with a 7-day interval between each attempt. FlyCode's AI/ML engine will handle retries independently.
ACH Retries: If you offer ACH as a payment method, leave the ACH retry toggle set to "ON."
ACH Failed Debit Emails: If you offer ACH as a payment method, ensure that the email notifications for failed bank debits are enabled.
Expiring card reminder emails: It is recommended to keep the expiring card email reminders enabled.
Open Invoices In Recovery To view invoices currently in the recovery process managed by FlyCode, navigate to the Stripe Invoices view and apply this filter. This will display all invoices that are actively being managed by the FlyCode app. To add the FlyCode Recovery flag to this view, click on the “Edit columns” button and select the “FlyCode Recovery (metadata)” property from the list. FlyCode Recovery Rate
To track overall recovery metrics, continue using Stripe’s Revenue Recovery dashboard. Invoices successfully recovered by FlyCode will be reflected in this dashboard. There is no change in the way Stripe displays this data.
Stripe In-Recovery Metrics: Due to some limitations in Stripe configurations, the “In recovery” definition in the recovery breakdown view (the orange section in the bar chart) is determined based on the custom recovery max duration defined in the retries setting tab (as mentioned in the Going Live Guide) and not accurately presenting the actual “In recovery” invoices total amount.
