These instructions are for the client-side version of Stripe Checkout, which runs entirely in the web browser with JavaScript.
Please see these instructions if you're using the server-side version of Stripe Checkout.
Step 1: Connect to Stripe
First, connect your Rewardful account to your Stripe account. This is a simple OAuth connection that allows us to receive events from your Stripe account associated with referred customers.
Rewardful integrates with Stripe Checkout by passing the unique click ID (i.e. referral ID) to Stripe as the clientReferenceId parameter when redirecting to checkout. It's important to note that Stripe Checkout will raise an error if clientReferenceId is set to a blank value. You may set this parameter to an arbitrary string if no referral is present.
Additionally, if the clientReferenceId parameter is already being used for another application or integration; consider using Stripe's metadata as an alternative approach. This method involves capturing the referral ID and appending it to the customer's metadata for proper attribution. Note, however, that Rewardful does not process referrals recorded during Stripe's Test Mode.
Step 2: Install JavaScript Snippet
Paste the following JavaScript snippet into the <head> tag:
<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>
<script async src='https://app.rewardful.dev/rw.js' data-rewardful='YOUR_API_KEY'></script>It must appear on every page of your application and marketing website. You would need to replace YOUR_API_KEY with your Rewardful dashboard's API key
Step 3: Pass referral ID to Stripe
When a visitor arrives on your website through an affiliate link, Rewardful creates a unique referral ID to represent that visitor. This value (a UUID string) must be passed to the stripe.redirectToCheckout() function call as the clientReferenceId parameter. For more complex scenarios or if the clientReferenceId parameter is already in use, consider using alternative methods such as metadata or promo code attribution for tracking referrals effectively.
In the example below, we add the clientReferenceId parameter to Rewardful.referral. If it is set, call the stripe.redirectToCheckout() function.
var checkoutParams = {
lineItems: [{ price: price, quantity: 1 }],
mode: mode,
successUrl: 'https://www.example.com/checkout?result=success',
cancelUrl: 'https://www.example.com/checkout/?result=cancel'
}
if (window.Rewardful && window.Rewardful.referral) { checkoutParams.clientReferenceId = window.Rewardful.referral;
}
stripe.redirectToCheckout(checkoutParams);
Advanced Use Cases and Recommendations
Metadata Tracking
For existing Stripe customers, append the referral ID to their metadata during the checkout.session.completed event.
Promo Code Attribution
Assign unique promo codes to affiliates to track referrals based on redeemed codes.
Testing and Verification
Ensure referral IDs are correctly passed as clientReferenceId or stored in the metadata of the Stripe customer record.
Conduct live tests for accurate Rewardful detection. Stripe Test Mode does not process referrals, or we don't read Stripe Test Mode data. Its sole purpose is to check if the referral ID is being retrieved correctly from the frontend and being passed to Stripe.