Attribution with Stripe

This guide walks you through the steps required to attribute referrals if your payment gateway is Stripe and includes:

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.

https://getmoonly.com/request-demo?ucc=UPobYBDuu0N&productId=getmoonly.com

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 function const ucc = await window.CelloAttribution('getUcc'); // otherwise window.CelloAttribution('getUcc').then((result) => { const ucc = result; })
Can your users sign up in your mobile app?

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:

I create Stripe customer at signup

Use this option if you create Stripe customer at the point of signup

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:

const stripe = require('stripe')('sk_test_51KiCYYCSMQAUBF...'); const customer = await stripe.customers.create({ description: 'New Stripe Customer', coupon: 'lHTYr6Y9', metadata: { cello_ucc: "hdz7afhs7", new_user_id: "xcsdad", // product user id of the new user new_user_organization_id: "123456" // organization id of the new user } });

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:

  1. Log in to Cello Portal and go to Webhooks to get your endpoint URL and authentication details.

  2. Log in to your Stripe dashboard.

  3. Select Webhooks from the left menu and select Add an endpoint

  4. 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.

  5. 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

  6. Get Signing secret from Stripe dashboard - go to the webhook you added and click Reveal under the Signing secret

  7. Copy the secret - copy the whole secret together with whsec_ prefix

  8. 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

I don't create Stripe customer at signup

If you don't create Stripe customer at signup and only at purchase, then you will need to use Cello API to send signup and Stripe Webhook to send transaction events

Use Cello API to send signup events

To send signup events, use Cello API /events endpoint.

Use the Domain base URL that corresponds with the environment.

Endpoint URL

Environment

https://api.sandbox.cello.so/

Sandbox

https://api.cello.so/

Prod

💡 Switch environments in the Portal using a switch to get the credentials


Authenticate

To use the Cello API, you need to authenticate the request using an accessToken which is passed in the Authorization request header.

To obtain them you will need accessKeyId & secretAccessKey which you can get from your product dashboard on Access Keys page.


Obtain accessToken & refreshToken

curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "accessKeyId": "<accessKeyId>", "secretAccessKey": "<secretAccessKey>" }' { "accessToken": "<accessToken>", "expiresIn": 18000, "refreshToken": "<refreshToken>" } Status Code 201

Refresh accessToken

curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "<refreshToken>" }' { "accessToken": "<accessToken>", "expiresIn": 18000 } Status Code 201

Send signup events

new-signup - the new user signs up for your product

POST https://api.cello.so/events { "eventName": "ReferralUpdated", "payload": { "ucc": "cello-ucc", "productUserId": "new-user-product-user-id", // or 'new-user-organization-id' "price": 0, "currency": "" }, "context": { "user": { "id": "new-user-product-user-id", "email": "new_user@gmail.com", "name": "New user name", "organizationId": "new-user-organization-id" }, "event": { "trigger": "new-signup", "timestamp": "2022-10-05 14:14:34" } } }

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:

const stripe = require('stripe')('sk_test_51KiCYYCSMQAUBF...'); const customer = await stripe.customers.create({ description: 'New Stripe Customer', coupon: 'lHTYr6Y9', metadata: { cello_ucc: "hdz7afhs7", new_user_id: "xcsdad", // product user id of the new user new_user_organization_id: "123456" } });

Connect Stripe Webhook

You will add a Webhook to your Stripe configuration to connect Stripe and Cello. This can be done in both test and production environments separately.

To set it up:

  1. Log in to Cello Portal and go to Webhooks to get your endpoint URL and authentication details.

  2. Log in to your Stripe dashboard.

  3. Select Webhooks from the left menu and select Add an endpoint

  4. 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.

  5. 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

  6. Get Signing secret from Stripe dashboard - go to the webhook you added and click Reveal under the Signing secret

  7. Copy the secret - copy the whole secret together with whsec_ prefix

  8. 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


Next to read:
Attribution with Chargebee
null
On This Page
Attribution with Stripe1. Track conversions on your landing page2. Track signups with Stripe4. Send signup and transaction events to CelloConnect Stripe WebhookUse Cello API to send signup eventsAuthenticateSend signup eventsAdd metadata to Stripe customerConnect Stripe WebhookAccess Ucc code during signupAdd metadata to Stripe customerObtain accessToken & refreshTokenRefresh accessToken