Introduction
This guide is required for enabling the FlexPay recovery engine to operate with Chargify's subscription service. Once the configuration is complete, Chargify 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.
Getting 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 [email protected].
There are six steps required to complete your integration.
- Get Chargify account information
- Configure Chargify Dunning and Retries
- Create your "Companies" in the FlexPay portal
- Configure the Currencies for your account
- Add the Chargify Integration
- Configure the Chargify Webhooks
1. Get Chargify account information
The setup requires a list of data points configured in the Chargify Platform:
- Subdomain: Used to generate a unique Chargify URL.
- Currency: One currency is defined on each Chargify Site.
- Shared Key: Used to secure the data exchange between Chargify and FlexPay.
- Dunning final action: Chargify Retries and Dunning system can configure how to handle the subscription state when the dunning is completed. Chargify Dunning Reference
- Chargify API Key: One Chargify API key is required to retry and cancel subscriptions.
- Payment Gateways: Provide your Client Success Manager with a list of all payment gateways (ex: Stripe, NMI, etc.).
1. To retrieve the “Subdomain” [1] and the “Currency” [2] you need to log into the Chargify site and gather the information from the Tile. If you need to return to the dashboard, you can do it by using the top-left drop-down and clicking on View All Sites.
2. To retrieve the Shared Key, click on the gear icon of your site and select Edit Site. Scroll down and copy the value under Shared Key.
3. We need to retrieve the current dunning configuration. It is possible that no dunning is currently configured and, in that case, this Step can be skipped. From the navigation menu, go to Config > Retries & Dunning. Then Select the Card Dunning option. From the existing schedule, click on three dots and select Edit. Go to the Final step and take note of it.
4. Now we need to create an API key. Go to Configs > Integrations using the navigation menu. Select the API Keys menu and click on the New API Key button. A screen will pop up and you must copy what is displayed under the Your API Key field.
5. We need to know which payment gateways are being used to confirm that they are properly supported by FlexPay. Go to Configs > Payment Gateways using the navigation menu. Make a note of all the connected gateways and send the list to your client success manager.
2. Configure Chargify Dunning and retries
We need to configure Chargify dunning and add an endpoint to send transactions to FlexPay.
1. In the Chargify portal, using the top-left drop-down, select the appropriate Site.
2. We need to configure the Chargify retries and dunning to match the FlexPay system.
► If there is a dunning strategy already configured:
- Go to Configs > Retries & Dunning using the navigation menu.
- Select the Card Dunning option.
- From the existing schedule, click the three dots and select Edit.
- Go to the Final step, click the three dots and select Edit.
- We need the value selected for the Final Action: Mark as Unpaid or Cancel Subscription
- The First Step and the Last Step are the only ones required. We need to remove any additional steps by clicking on the three dots, then the Delete button.
- Make a note (or take a screenshot) of all existing Steps
► If there isn't a dunning strategy configured:
- Go to Configs > Retries & Dunning using the navigation menu.
- Select the Card Dunning option.
- Click on Create Dunning Schedule.
- Select Custom Dunning Schedule
- Please provide a meaningful name, we recommend you use "FlexPay Dunning".
- The First Payment Failure should look like this (No Email)
- Configure the Final Step by clicking on the ellipsis button of the Final Step and click on Edit. The Day After Due Date must be set to 32, the Final Action must match the one configured on Step 1.3, Retry Payment must be checked and the Send Email option should not be checked. Then click on Save Step.
Note: Regardless of any previous dunning strategy, the final result should have 2 steps and must look like this
The FlexPay retry logic will disable the capacity to send emails while using the dunning workflow We want all dunning steps to be configured with the value No Email
3. Create your "Companies" in the FlexPay portal
When adding your companies, you need to create one per Chargify Site. Please follow the regular process as described here Adding Companies to Your FlexPay Account
4. 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 Chargify is configured to accept.
5. Add the Chargify Integration
- In FlexPay's portal, go to Account Setting > Integrations > Chargify
- Click on the Add Chargify button
- Enter the information in the Manage Integration Point page
Chargify Integration Details
Name: Configuration name (we recommend you use the Account Name you have in Chargify)
Company: Choose the appropriate company from the dropdown list.
Environment: Options are “Live” and “Sandbox”. Please select “Live”
Status: Options are “Enabled” or “Disabled”.
Note: When an Integration is set to Status “Disabled”, the Webhook and FlexPay Listener will be disabled on Chargify'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 API key provided to FlexPay.
Settings
Select a currency: Please enter the currency as noted on Step 1.1.
Subdomain: Please enter the subdomain as noted on Step 1.1.
API key: Please enter the key created on Step 1.4 of this guide.
Shared key: Please enter the value gathered on Step 1.2 of this guide.
Final action: If all retries for a payment fail, your options are:
- Cancel subscription – the subscription will transition to the ‘cancelled’ state and it will cease to accrue any new charges
- Mark as unpaid – the subscription will transition to the ‘unpaid’ state, but it will continue to accrue new charges
- No action: doesn’t update the Subscription status
Final action delay: the action selected in the previous step will occur 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 action occurs immediately.
- Once completed, click Add Integration Point
- The FlexPay webhook URL will be displayed. Take note of it since you will need it in the following section
6. Configure Chargify Webhooks
We need to configure a Chargify webhook and add an endpoint to send transactions to FlexPay.
1. We need to configure the Chargify Webhooks using the Webhook URL provided by FlexPay. Go to Configs > Settings using the navigation menu. Then Select the Webhooks menu. Please make sure the checkbox under Webhooks are enabled is checked and click on the Add New Endpoint button.
2. We need to add the FlexPay Webhook URL provided by FlexPay. In the Webhook Subscriptions list we need to check the following items: Payment Success, Payment Failure, and Refund Success. Click on the Save button.
3. You can test the configuration by clicking on “Actions” and the “Test” button. A successful message will be displayed.
