Failed Payment Recovery

Recover lost revenue from failed payments automatically.

Overview

When a customer’s payment fails, you can show a pop-up anywhere on your site that explains the issue and allow them to update their card right away.

If they close the pop-up without fixing the issue, it turns into a small banner that stays on your site reminding them to update their payment without getting in the way.

Quick Setup

How to add recovery popups to your website or app:

To get started with the Failed Payment Recovery flow, follow these three simple steps:

Step 1 : Insert the Churn Solution JS Embed Code

The following code will add the Churn Solution client-side script and make itself available in the global JS namespace as window.churnsolution. You can use it to start the off boarding process for your customers. Just add it to the <body> section of your HTML.


<script>
    !function(){
        if (!window.churnsolution || !window.churnsolution.ready) {
            window.churnsolution = { ready: true };
            const s = document.createElement('script');
            s.src = 'https://app.churnsolution.com/sdk/index.min.js';
            s.async = true;
            const e = document.getElementsByTagName('script')[0];
            e.parentNode.insertBefore(s, e);
        }
    }();
</script>

Or you add it to the <head> section of your HTML as:


<script src="https://app.churnsolution.com/sdk/index.min.js"></script>

Step 2: Server-side authentication

Server-side authentication is implemented to ensure that all requests sent by Churn Solution to your payment provider on your behalf are valid and authorized. You can do it by generating an HMAC hash (SHA256 algorithm) with the API_KEY and your STRIPE_SUBSCRIPTION_ID key.

You can find your API_KEY in Account setting page.

Replace "STRIPE_SUBSCRIPTION_ID" with your actual Stripe subscription ID.

Before starting the Churn Solution flow, you should send a request to your server. This request will validate its permission usually through existing authorization measures for user actions. The hash generated by this code should be sent to front end to be used in the next step.

Below are some examples of how this hash can be generated in different backend languages.


private static String getSha256HmacHash(String API_KEY, String STRIPE_SUBSCRIPTION_ID) throws NoSuchAlgorithmException, InvalidKeyException {
    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
    sha256HMAC.init(secretKeySpec);

    byte[] hash = (sha256HMAC.doFinal(STRIPE_SUBSCRIPTION_ID.getBytes()));
    StringBuffer result = new StringBuffer();
    for (byte b : hash) {
       result.append(String.format("%02x", b));
    }
    return result.toString();
}

Step 3: Run the Churn Solution Script:

Once the script is ready and you have the authKey, run the recovery flow using the following code:


window.churnSolution?.checkFailedPayment(
    authKey,                     // HMAC hash from your backend
    stripeSubscriptionId,        // Customer's Stripe subscription ID
    'APP_ID',                    // App ID from Churn Solution dashboard
    {
        // options
        record: true,
        email: '',
    }
);

You can find your APP_ID in Integration page, after successfully linking your account with Stripe.