Maxio/Chargify Configuration Guide

Daniel Charry

Modified on: Wed, Dec 6, 2023 at 5:11 PM

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 support@flexpay.io.

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.

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.

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.