Stripe Subscription Billing Configuration Guide

Introduction

This guide is required for enabling the FlexPay recovery engine to operate with Stripe's subscription billing service. Once the configuration is complete, Stripe will use webhooks to notify FlexPay when an event happens. FlexPay will then trigger the next retry attempt at a specific date and time based on the recommendation from our AI-machine learning engine

The FlexPay integration with Stripe facilitates recovery for both account-level events and connected accounts. During setup, ensure that the endpoint is created appropriately, as only one option is supported at a time. The integration functions either at the account level or the connected accounts level, but not simultaneously. If you require both functionalities, please reach out to us for assistance.

Workflow Validation

The Getting Started section of this guide will get you on the right path to completing a successful Stripe/FlexPay integration. We understand that certain scenarios and/or requirements may differ from merchant to merchant, which is why we strongly recommend that before integrating your production account, you run through the steps outlined below with Stripe in Test Mode (a test API key starts with rk_test...). This will allow you to validate in a safe environment your most common scenarios without affecting any of your production data. Please work closely with your CSM or Integration Manager since you will need their assistance with some of the steps below.

Start by testing the following:

1. An approved recurring payment.
   • Successful if you see the approval in the Transactions section of the FlexPay portal
2. A refund transaction
   • Successful if you see the refund in the Transactions section of the FlexPay portal
3. A failed recurring payment (soft decline)
   • Successful if you see the decline in the Transactions section of the FlexPay portal &
   • If there is a retry scheduled in the coming days
4. A failed recurring payment (hard decline)
   • Successful if you see the decline in the Transactions section of the FlexPay portal &
   • If the subscription is canceled (or it follows what was configured for "Subscription Status" and "Invoice Status")

Once validation is complete, you can move forward and configure your production account with confidence and little to no room for unexpected events.

Getting Started

This guide requires you to have your FlexPay account already setup. If you have not done this, please contact your Client Success Manager, or send an email to support@flexpay.io.

There are six steps required to complete your integration.

1. Create two API keys in Stripe
2. Add FlexPay's IP address to Stripe's allow list (optional)
3. Deactivate Smart Retries (including any other automated dunning solution)
4. Create your "Companies" in the FlexPay portal
5. Configure the Currencies for your account
6. Add the Stripe integration

Note: Soon after activating the integration between Stripe and FlexPay, you may notice more cancellations in Stripe's dashboards. This happens because some subscriptions flagged for recovery in Stripe might be canceled once they enter FlexPay's recovery process. FlexPay follows Visa and Mastercard rules and doesn't attempt retries for hard declines. So, expect a temporary (1-2 weeks) increase in churn as part of this integration.

1. Create two API Keys in Stripe  

API Keys are required for FlexPay to access and update the Stripe entities.  FlexPay will require two Restricted API keys with no expiration dates.  

1. FlexPay Primary Key 
2. FlexPay Fallback Key - only used if the API transactions/second limit is exceeded on the Master Key  

These are the steps needed to create a restricted API key in Stripe:  

• Navigate to the API Keys page in the Developers module https://dashboard.stripe.com/apikeys 

• Click the “Create restricted key” button.
• Next, Select the option "Providing this key to another website" and click Continue.
• For the website details, enter FlexPay as the name, and https://www.flexpay.io as the URL. Check the option Customize permissions for this key and Click Continue

• Stripe may have automatically selected permissions that are not required for FlexPay. Set everything to none, except the settings highlighted below. 

• If the integration is intended to recover payments on Connected Accounts, make sure the permissions are set in the CONNECT PERMISSIONS column, otherwise, set them in the PERMISSIONS column. If you only see one column, please proceed accordingly. 

• Name the key “FlexPay Primary Key” and click “Create key”
• Copy the key to a safe place. You will not be able to view it after you click Done.
• Click Done

Once the 1^st Key is created. You need to repeat the same process and create a 2^nd Key using the "Duplicate Key" feature. Use the name “FlexPay Fallback Key”

• In the Restricted Keys section, find the "FlexPay Primary Key" and click on the three dots at the end.
• Click on "Duplicate Key..."

• Change the Key name to "FlexPay Fallback Key" 
• Scroll down and click "Create Key"
• Copy the key to a safe place. You will not be able to view it after you click Done.
• Click Done

If your Client Success Manager is configuring your account in the FlexPay portal, you will need to share both keys using a secure transfer method.  

Below are the configuration settings for the Restricted API Keys along with details explaining why we need the permissions as well as the errors we might see in FlexPay if the permissions are not properly configured.  

2. Add FlexPay IP to Stripe's allow list (optional)

Follow these steps to add FlexPay’s IP to the “Allow” list:  

• Click on the Settings icon

• Click on the “Lists” link in the Radar section  

• Click on “Client IP address allow list”  

• Click on “+ Add item” button. If no items exist, it will be labeled as “+ Add your first item”  
• Add the following IP to the “Single IP address” box: 13.65.95.109 

• Click the “Add” button

3. Deactivate Stripe Smart Retries 

Now you must deactivate Smart Retries (or any other third-party dunning solution) on the Stripe Portal and configure the system to support FlexPay. If you have custom retry rules in place, you must delete them. Please make a note (screenshot) of the existing rules before removing them.

• Click on the Settings icon

• Under Product settings, click on Billing 

• In the Subscriptions and Emails tab, scroll down to the “Manage failed payments for subscriptions” section  
• Make a note (or take a screenshot) of existing rules  
• Click on “Use custom retry schedule for subscriptions”. If it’s already selected, remove any existing rules by clicking on the “X” next to the rule  

• Disable “Send emails when card payments fail”  
• Set the Subscription status to “leave the subscription past-due"  
• Set the Invoice status to “leave the invoice past-due"  
• Click on the “Save” button. When you are done, it should look like this:

4. Create your "Companies" in the FlexPay portal

When adding your companies, you need to create one per Stripe account. Please follow the regular process as described here Adding Companies to Your FlexPay Account

5. Configure the Currencies for your account

In order to add currencies to your account, you must complete the following steps:

• Go to Account Settings > Platform Configurations under the admin section of the Client Portal. 
• Scroll down to Account Currencies and click on Manage Currencies.
• Select the Currencies your Stripe is configured to accept. 

• Click SAVE CONFIG

6. Add the Stripe integration

• In FlexPay's portal, go to Account Setting > Integrations > Stripe 
• Click on the “Add Stripe” button

• Enter the information in the "FlexPay to Stripe" tab

Stripe Integration Details

Name: Configuration name (we recommend you use the Account Name you have in Stripe)

Company: Choose the appropriate company from the dropdown list.

Environment: Options are “Live” and “Sandbox”. Please select “Live”

Status: Options are “Enabled” or “Disabled”.

Description: Since this will show in the webhook, we recommend you use “FlexPay Webhook EndPoint”

Settings

API Key Type: Drop Down Options are “Restricted” or “Standard”

Please select “Restricted” by default. The Standard Key isn’t recommended as it would grant FlexPay full access to your Stripe configuration, providing FlexPay more access than is needed. Both the Standard and Restricted Key will work, but we recommend Restricted.

API Key 1: Please enter the Master API Key you created at the start of this guide.

API Key 2: Please enter the Fallback API Key you created at the start of this guide. It will only be used when too many simultaneous requests are made with the Master Key. 

Subscription Status: If all retries for a payment fail, your options are:

• Cancel End of Period – Stripe functionality will cancel the Subscription at the end of the subscription end date
• Cancel Subscription with delay – Stripe functionality will cancel the Subscription at the moment of a hard decline PLUS  X-Days and X-Hours as shown below. If you leave the settings at 0 days/0 hours, the subscription will cancel immediately. NOTE: Please keep in mind that proration is enabled by default in Stripe. This option may give proration credits to your customers Learn about prorations
• Cancel Subscription with delay (with no proration) –  Same functionality as the previous option, but proration will not apply. When a subscription is cancelled, no credit will be given to your customer. 
• Leave Subscription As-Is: doesn’t update the Subscription status

Invoice: If all retries for a payment fail. –  Options are:

• Mark the invoice as uncollectible when subscription cancels - Sets the Invoice status to Uncollectible. This option will also send fp-uncollectible: true metadata to both Invoice and Subscription.
• Leave Invoice As-Is – The Invoice remains in “Failed” status while FlexPay is attempting to recover the payment. When FlexPay is unable to recover the payment, the Invoice will remain in “Failed” status.

• Once completed, click "Next"

In the "Stripe to FlexPay" tab, you have to choose if you want to manually create the webhook in Stripe, or if you want FlexPay to handle it via the API (this is our recommended method). 

• If you want us to handle the webhook creation, choose "Yes".
•  If the integration will be working with Connected Accounts in Stripe, select "Connected accounts" under "Configure webhook to listen to events on", otherwise leave "Main account" selected.
• Once completed, click "ADD STRIPE INTEGRATION"

In the "Existing Invoices in Stripe's Failed Payment Processing" tab, you can let FlexPay take over existing failed invoices. This process brings all the open overdue invoices that are “AutoPayment” to the FlexPay platform to be retried. This will include invoices that have Failed & Retrying. You can “un-check” the takeover process and choose to trigger it after the Stripe integration is created by updating the integration.

• Tick the checkbox if you want FlexPay to take over.
• Finally, click "SAVE STRIPE INTEGRATION"

You have completed setting up FlexPay to run decline salvage on your Stripe account.

If ANY of these steps are unclear, please, email us for assistance at: integrations@flexpay.io