Installing Churnkey
Details for developers on adding ChurnKey to your app

Adding the ChurnKey Module

The following code will add the ChurnKey module under the window.churnkey namespace so that you can later initialize the offboarding flow for your customers. Place it in the HTML <head> element.
1
<script>
2
!function(){
3
if (!window.churnkey || !window.churnkey.created) {
4
window.churnkey = { created: true };
5
const a = document.createElement('script');
6
a.src = 'https://assets.churnkey.co/js/app.js?appId=YOUR_APP_ID';
7
a.async = true;
8
const b = document.getElementsByTagName('script')[0];
9
b.parentNode.insertBefore(a, b);
10
}
11
}();
12
</script>
Copied!

Server Side Authentication (HMAC)

Server side verification is in place to make sure all customer requests that ChurnKey makes on your behalf are authorized. This is put in place by using a server side generated HMAC hash on the Stripe customer id.
Concretely, before the ChurnKey flow is triggered, you should send a request to your server which (a) verifies that the request is valid - typically using whatever authorization guards you already have in place for user actions and then (b) hashes that customers Stripe id using the SHA-256 hashing function.
Below are snippet examples of how this hash can be generated in different backend languages.
Node.js
Python (Django)
Ruby (Rails)
PHP
Go
Java
1
const crypto = require("crypto");
2
const user_hash = crypto.createHmac(
3
"sha256",
4
API_KEY // Your Churnkey API Key (keep this safe)
5
).update(CUSTOMER_ID).digest("hex"); // Send to front-end
Copied!
1
import hmac
2
import hashlib
3
email_hash = hmac.new(
4
API_KEY, # Your Churnkey API Key (keep safe)
5
CUSTOMER_ID, # Stripe Customer ID
6
digestmod=hashlib.sha256
7
).hexdigest() # Send to front-end
Copied!
1
OpenSSL::HMAC.hexdigest(
2
"sha256",
3
API_KEY, # Your Churnkey API Key (keep safe)
4
CUSTOMER_ID # Stripe Customer ID
5
) #send to front-end
Copied!
1
<?php
2
echo hash_hmac('sha256', CUSTOMER_ID, API_KEY); // Stripe Customer Id
3
?>
Copied!
1
package main
2
3
import (
4
"crypto/hmac"
5
"crypto/sha256"
6
"encoding/hex"
7
)
8
9
func main() {
10
hash := hmac.New(sha256.New, API_KEY)
11
hash.Write(CUSTOMER_ID)
12
hex.EncodeToString(hash.Sum(nil))
13
}
Copied!
1
import javax.crypto.Mac;
2
import javax.crypto.spec.SecretKeySpec;
3
4
public class Test {
5
public static void main(String[] args) {
6
try {
7
String secret = API_KEY; // API Secret
8
String message = CUSTOMER_ID; // Stripe Customer Id
9
10
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
11
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
12
sha256_HMAC.init(secret_key);
13
14
byte[] hash = (sha256_HMAC.doFinal(message.getBytes()));
15
StringBuffer result = new StringBuffer();
16
for (byte b : hash) {
17
result.append(String.format("%02x", b));
18
}
19
System.out.println(result.toString());
20
}
21
catch (Exception e){
22
System.out.println("Error");
23
}
24
}
25
}
Copied!

Initializing the ChurnKey Flow

Once the HMAC hash has been generated, you can initialize and display the ChurnKey offboarding flow by calling window.churnkey.init('show'). Typically, you will attach an event listener to a "cancel" button.

Adding the authHash

Simply use the Server Side Authentication section above to implement an HMAC hash function and pass that value into the authHash parameter.

Updating a Single Subscription (customerId vs subscriptionId)

In addition to the customerId parameter, you'll need to pass in subscriptionId as shown below. This approach is useful when customers have multiple subscriptions and you want precise control over exactly which subscription is being paused, discounted, or canceled. If you don't support multiple subscriptions and have no intention of doing so, the approach described in the next section might be appropriate.
1
document.getElementById('cancel-button').addEventListener('click', function () {
2
window.churnkey.init('show', {
3
// Add subscriptionId 👇 👇 👇
4
subscriptionId: 'SUBSCRIPTION_ID' // optional
5
customerId: 'CUSTOMER_ID', // required
6
authHash: 'HMAC_HASH', // required
7
appId: 'YOUR_APP_ID', // required
8
mode: 'live', // set to 'test' to hit Stripe test environment
9
record: true, // set to false to skip session playback recording
10
})
11
})
Copied!

Updating Customer Billing

If you want Churnkey to make changes more broadly across the customer's entire billing record, you should omit the subscriptionId parameter while still including the required customerId parameter. This is useful when a customer has multiple plans and you want offers to apply to all current billing.
For example, a pause would put a hold on all billing (even if there are multiple subscriptions). A discount would be applied to the customer record so all of their subscriptions would receive the same discount rate. Finally, a cancellation at the user level would cancel all underlying subscriptions.
1
document.getElementById('cancel-button').addEventListener('click', function () {
2
// SEE SERVER SIDE AUTHENTICATION ABOVE FOR HMAC_HASH
3
window.churnkey.init('show', {
4
customerId: 'CUSTOMER_ID',
5
authHash: 'HMAC_HASH',
6
appId: 'YOUR_APP_ID',
7
mode: 'live', // set to 'test' to hit Stripe test environment
8
record: true // set to false to skip session playback recording
9
})
10
})
Copied!

Enable Session Recording

1
record: true
Copied!

Live Mode vs. Test Mode

Each mode corresponds to the Stripe environment you're working in. When set to live mode, changes will hit your production Stripe environment. If you're not ready for live data, you can just set mode to test and Churnkey will work with your Stripe account test data.
1
mode: 'live', // or 'test'
Copied!
Test mode corresponds to this toggle in your Stripe account

Where to find your App Id

Your appId is displayed within the code snippet we provide in your account settings. Simply navigate here to locate it https://app.churnkey.co/settings/embed.

Last modified 2mo ago