⚠️

Note: Integrating with Stripe is in beta

Our impact.com integration with Stripe is currently in beta. Should your experience not match the guide below, please reach out to your CSM (or contact support).

Stripe is a software service provider for end-to-end billing, invoicing, payments, and subscription management. With impact.com’s B2B offering, you can run affiliate programs that drive new subscription sign-ups and you can reward partners based on recurring payments from these sign-ups. impact.com integrates with Stripe to track one-time payments and subscriptions.

Understand the integration limitations

impact.com only supports the following tracking events on Stripe:

• One-time payments (Refer to checkout Session object).
• Subscriptions (Refer to invoice object).

The integration can differentiate between a first subscription event and recurring subscription events, but it can't differentiate between recurring events. This process is done with the billing_reason field.

• When billing_reason=subscription_create, it is sent using the First Subscription tracker ID.
• When billing_reason=subscription_cycle, it is sent using the Recurring Subscription tracker ID.

Currently, we only support two billing_reason values for the invoice object: subscription_cycle and subscription_create.

Only invoice.paid, checkout.session.completed, and charge.refunded events are supported.

16 Webhook events can be registered per Stripe account - if you are already at the maximum amount, you won’t be able to integrate with impact.com until you delete some.

How it works

• On your website (or store), you'll implement a script that captures an impact.com Click ID (irclickid) value from the user's browser, then add it as a metadata property to the Stripe subscription record.
• You'll then generate read-only Stripe API credentials for impact.com to use.
• You'll provide Stripe API credentials for impact.com via our partner integration portal, which will generate URLs for the webhooks.
• Once authenticated, the integration uses Event Webhooks to capture invoice.paid, checkout.session.completed, and charge.refunded events from Stripe and send to your impact.com account.
  Please keep in mind that Stripe only allows the registration of up to 16 webhook endpoints. impact.com cannot register additional webhook URLs if you exceed the limit set by Stripe.

Pre-requisites (with impact.com)

This section covers the prerequisites to meet before connecting the impact.com app to your Stripe account.

Capture the Click ID

1. Implement UTT

impact.com needs to generate and capture clickId values for visitors to your store, so you need to implement impact.com's Universal Tracking Tag (UTT) to your store. The UTT provides a series of functionality that would ease you into capturing and handling the clickId. To capture the clickId, you must obtain your account’s UTT script from impact.com’s platform and set it up to load on every public page of your site.

Retrieve the UTT

2. Capture the irclickid and add it to the payment form

The UTT provides the generateClickId function that you can use to fetch the irClickId value required to be able to track conversions. Copy the full script tag below into your clipboard.

ire(‘generateClickId’, callback);

• Callback: Receives the captured `clickId` as a parameter and you can freely manipulate it to include it in Stripe's subscription payment form. You can then send this information to your backend for later processing.

⚠️

Note:

Add the to the clickId to the UTT on every public page of your site.

The example below indicates how you could capture the irClickId using the UTT generateClickId function and set the value in a hidden field of a form on a field with id impact_ClickId using jQuery.

ire(‘generateClickId’, function (clickid) {
  $(‘#impact_clickid’).val(clickid);
});

Send the clickId to Stripe

Modify the creation method call

Modify the creation method call by adding an impact_Click_Id field to the metadata of the Stripe subscription to be able to track conversions.

<script type="text/javascript">
const stripe = require('stripe')('{{your_own_Stripe_key}}');

const subscription = await stripe.subscriptions.create({
  customer: 'cus_KlZATjx0ZYpUvR',
  items: [
    {price: 'price_1K622pHt43s58jkaFFS3mnH5'},
  ],
  metadata: {‘impact_click_id’: request.impact_clickid}
});

</script>

The request.impact_ClickId method is assuming the customer can retrieve that value via

{‘impact_click_id’: request.impact_clickid} })

The above is simply a recommendation. You can choose to accomplish this requirement in a way that works best for your setup. The end goal is to ensure the irClickId value can be captured from the landing page query string, stored, and then added as a metadata property call impact_Click_Id against the Stripe subscription record, so that when the Stripe App receives the invoice.paid webhook, that value in the payload.

Verify the creation method call

Integration Setup

⚠️

Note: Integrate via the Stripe app

Refer to as Integrate via the Stripe App an alternative method to integrate with Stripe.

Generate a Stripe API key

Choose between the default secret_key that Stripe provides or create a restricted_key with the appropriate permissions.

Configure the Stripe Integration

impact.com Account information reference

Account Data	Description
URL*	The URL of the site where your integration will be implemented.
Auth Token*	In impact.com, navigate to [Menu] → Settings → API to find your Auth Token. Copy the full case-sensitive value.
Program Id*	Enter your impact.com Program ID value (a.k.a Campaign ID value). To find this value, select your brand name in the top left corner of Impact. Your Program ID is shown in gray type under your Program name in the Program column.
Event Type Id*	In impact.com, navigate to [Menu] → Settings → Tracking → Event Type to find your Event Type ID. Copy the full case-sensitive value.
Recurring Event Tracker Id*	Your impact.com recurring subscription Event tracking identifier. In impact.com, navigate to [Menu] → Settings → Event Type. This event type must be linked as a child event to your first subscription event type. For help with creating and linking event types, contact support
API Key*	Refer to the Stripe API Key you created in the section above.

View the required Stripe permissions for this integration...

1. All core resources: Read
2. All Checkout resources: Read
3. All Billing Resources: Read
4. All Connect resources: Read
5. All Orders resources: Read
6. All Issuing resources: None
7. All reporting resources: None
8. All webhook resources: Write
9. Stripe CLI permissions: None
10. All Payment Links resources: None

If the integration is successful, a listing for your integration should appear in the dashboard.

Integration creation

When a Stripe integration is first created using the api_key in the creation form, two webhooks will be registered in the Stripe backend using the Stripe Webhook API and listed in the following 3 events:

• invoice.paid: This event handles subscriptions. Each recurring subscription billing will have a unique invoice ID.
• charge.refunded: The request is delayed by one hour before it is sent to impact.com.
• checkout.session.completed: This event handles standalone payments.

Reports

Subscription events

When an invoice.paid event triggers in Stripe, a request is sent to Impact conversions API endpoint with the following data mapping:

One-time payment events

When a checkout session is completed, the request is made to impact.com with the following data mapping:

Refunds

When a charge.refunded event triggers in Stripe, a request is sent to Impact and will process an hour later to ensure the initial conversion is fully processed, with the following data mapping: