FlyCode's app for Stripe

Maximize Subscription Revenue and increase retention with failed payment AI & Payment optimization

Introduction

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.

How FlyCode is different from Stripe payment recovery for failed payments?

Setup

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.

Technical Overview

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 portal as will be explained below.

FlyCode architecture diagram

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 portal:

• Invoice Page UI: The flycode_recovery: true metadata field will be visible within the invoice details.

  

  The invoice details section

• 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.

  

  The invoice logs section

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.

  • 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.

    

    The invoice page
  • 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).

    

    The recent activity timeline section
• 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.

  

  The invoice logs section
• 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.

  

  The payments view

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:

• 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.

  

  The subscription page
• 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.

  

  The invoice activity and logs sections
• 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.

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:

1. 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.

   

   The revenue recovery retries configuration tab (status update)
2. 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.

   

   The revenue recovery retries configuration tab (retries duration)
3. ACH Retries: If you offer ACH as a payment method, leave the ACH retry toggle set to "ON."

   

   The revenue recovery retries configuration tab (ACH)

Emails Setting

To be configured from here. Follow these steps to configure your payment-related email settings:

1. 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.

2. ACH Failed Debit Emails: If you offer ACH as a payment method, ensure that the email notifications for failed bank debits are enabled.

   

   The revenue recovery emails configuration tab (failed payments)
3. Expiring card reminder emails: It is recommended to keep the expiring card email reminders enabled.

   

   The revenue recovery emails configuration tab (expired cards)

What to Expect After Going Live

After launching the FlyCode App, you can monitor its performance and impact directly from your Stripe portal.

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.

The invoices list (filtered)

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.

The edit columns overlay

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.

The revenue recovery dashboard

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.

• 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.

  

  The revenue recovery dashboard tooltips
• 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