Support

Submit a ticket My tickets Knowledge Base API Reference
Welcome
Login  Sign up
Open navigation

Stripe Configuration Guide for FlexPay

Introduction

This guide is required for enabling the FlexPay decline salvage solution 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.


Before We Get Started

This guide requires you 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

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:  

  • Click the “Create restricted key” button and name it “FlexPay Primary Key”
  • Configure the key with the settings highlighted below 

  • 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 1st Key is created. You need to repeat the same process and create a 2nd 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 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.  

► Click to view the permissions table
Access namePermissionsDetailsErrors if not done
ChargesRead1. Allow reading charge details as chargeId is used as OrderId for flexpay.
2. Other info like decline reason in ChargeOutcome sub object
The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_charge_read' permission would allow this request to continue
CustomersReadCustomer information, such as Name, Address, phone, etc., is used as additional data points in FlexPay’s ML modelsThe provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_customer_read' permission would allow this request to continue.
PaymentIntentsReadPayment Intents contains important information, such as whether an invoice requires 3DS action. The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_payment_intent_read' permission would allow this request to continue.
InvoicesWriteAllow flexpay to read invoice data, retry invoice and cancel invoice

StripeException The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_credit_note_read' permission would allow this request to continue.

The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_invoice_write' permission would allow this request to continue
SubscriptionsWriteWill allow to read past-due subscriptions, read specific subscription information, and update the subscription status (ex: cancel) 

StripeException The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_subscription_read' permission would allow this request to continue.

The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_subscription_write' permission would allow this request to continue.
Webhook EndpointsWriteTo allow FlexPay to create/update webhooks when creating an integration pointStripeException The provided key 'rk_test_*****' does not have the required permissions for this endpoint on account 'acct_*****'. Having the 'rak_webhook_write' permission would allow this request to continue.

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

This section is only needed if you have the "Radar List" option enabled for your Stripe account

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

  • Click on “Subscriptions and emails” in the Billing section 

  • 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 as-is"  
  • Set the Invoice status to “leave the invoice as-is"  
  • Click on the “Save” button. When you are done, it should look like this:

Note: Subscription Status and Invoice Status will be determined as per the FlexPay Configuration done later in this process. If the “Send emails” option isn’t turned off, emails will be sent on every failed charge.


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”

Note: When an Integration is set to Status “Disabled”, the Webhook and FlexPay Listener will be disabled on Stripe's end AND FlexPay end. However, transactions that are already scheduled to be retried at a future date in FlexPay will still run. In order to stop this from happening, you must delete the restricted key provided to FlexPay.

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. – 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. NOTE: If you leave the settings at 0 days/0 hours, the subscription will cancel immediately.
  • Leave Subscription As-Is: doesn’t update the Subscription status

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

  • Uncollectible - Sets the Invoice status to Uncollectible in Stripe. https://stripe.com/docs/invoicing/overview#uncollectible 
  • 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"
Note: Whether you are creating or updating the integration and you click “Next,” it will save and record whatever the configurations are on the page. For example, if you are updating an existing integration and you choose "disable" as the status, then go to the next screen, and then hit cancel, it will be disabled, even though you hit “cancel” on the next page.

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 you decide to create the webhook yourself, please reach out to support@flexpay.io and we can offer some guidance on how to get it configured.
  • 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.

The “TakeOver Process” is a one-time process executed when you are first onboarded to FlexPay.

  • 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

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.