Attribution with Stripe
This guide walks you through the steps required to attribute referrals if your payment gateway is Stripe and includes:
- Tracking conversions on your landing page
- Tracking signups with Stripe
- Sending signup and transaction events to Cello
1. Track conversions on your landing page
Add Attribution library to your Home page by including the following script in the <head> tag to track attributions and show New user banner.
<script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>2. Track signups with Stripe
When a signup finally happens, you need to make sure that a ucc code, identifying the referrer, is saved to the new user record and passed to Stripe upon customer creation.
Access Ucc code during signup
Ucc is present in the URL of your Home page when a new user is redirected to it from the invite link and in the cookies, added by the Attribution library.
To access the ucc during signup, you can use the Attribution library JS method getUcc().
Here is how to do it:
- Add the following javascript code before any of the calls to the library to avoid race conditions.
window.CelloAttribution=window.CelloAttribution||async function(t,o){if("getReferral"===t)throw new Error("getReferral is not supported in this context. Use getUcc instead.");let e,n;const i=new Promise((t,o)=>(e=t,n=o));return(window.CelloAttributionCmd=window.CelloAttributionCmd||[]).push({command:t,args:o,resolve:e,reject:n}),i};// if in async functionconst ucc = await window.CelloAttribution('getUcc');// otherwisewindow.CelloAttribution('getUcc').then((result) => { const ucc = result;})To make sure your referrers get rewarded when a new user signs up in the mobile app, follow this guide on Mobile attribution to track mobile app signups.
Now the next step depends on your flow!
4. Send signup and transaction events to Cello
Choose one of the 2 options depending on your scenario:
- I create Stripe customer at signup - Use only Stripe Webhook integration if you create Stripe customer at the point of signup
- I don't create Stripe customer at signup - Use a combination of Cello API and Stripe Webhook integration if you don't create Stripe customer at signup and only at purchase
Pick your scenario:
Add metadata to Stripe customer
Use Stripe.js to modify customer fields you send upon customer creation:
- cello_ucc - ucc, a referral code identifying the referrer
- new_user_id - a unique user ID in your system, identifying the new user who just signed up. This should be the same ID (productUserId) you will use to boot the Referral component, when this user logs into your app
- new_user_organization_id (optional) - add this, if your referrers can refer an organization rather then a single user and you want to reward based on that.
💡 In this step, we also recommend adding the new user discount field (coupon), so when the customer later subscribes and the subscription is created in Stripe, the discount will be applied automatically. More information on how to grant discounts in Stripe can be found in this guide.
Here is an example for a NodeJS App:
Connect Stripe Webhook
You will add a Webhook to your Stripe configuration to connect Stripe and Cello. This can be done in both sandbox and production environments separately.
💡 Switch environments in the Portal using a switch to configure Sandbox and Production separately.
To set it up:
- Log in to Cello Portal and go to Webhooks to get your endpoint URL and authentication details.
- Log in to your Stripe dashboard.
- Select Webhooks from the left menu and select Add an endpoint
- Enter the provided Endpoint URL based on the environment. Cello Endpoint URL is available for both test and production environments. You can get Endpoint URL in you product dashboard on Webhooks page.
- Select the events:
charge.refunded,charge.succeeded,charge.updated,customer.created,customer.deleted,customer.updated,customer.subscription.created,customer.subscription.deleted,customer.subscription.updated,invoice.paid - Get Signing secret from Stripe dashboard - go to the webhook you added and click Reveal under the Signing secret
- Copy the secret - copy the whole secret together with
whsec_prefix - Add Signing secret to Cello Stripe webhook integration - got to Webhooks page, click on Add webhook secret, paste in your Stripe Signing secret and save