Stripe Server-Side Checkout

Instructions for Stripe Checkout (server-side)

Emmet Gibney avatar
Written by Emmet Gibney
Updated over a week ago

These instructions are for the server-side version of Stripe Checkout, which runs on your server using the Checkout Session API.

Please see these instructions if you're using the client-side version of Stripe Checkout, which uses JavaScript in the web browser.


Rewardful integrates with Stripe Checkout by passing the unique click ID (i.e. referral ID) to Stripe as the client_reference_id parameter when redirecting to checkout. It's important to note that Stripe Checkout will raise an error if client_reference_id is set to a blank value, so it should only be sent when present.

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.

Step 2: Install JavaScript Snippet

Paste the following JavaScript snippet into the <head> tag:

<script async src='' data-rewardful='YOUR_API_KEY'></script>

It must appear on every page of your application and marketing website.

Step 2: Pass the referral ID from the browser to your server

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 from the browser to your server so it can be included in the Stripe API call that initiates a Checkout session.

You can use our JavaScript API to send the referral ID (Rewardful.referral) from the web browser to your server via AJAX, or insert Rewardful's hidden input. within a form that's submitted to your server.

Step 3: Pass the referral ID to Stripe

Note: These examples use Ruby as the programming language, but the same concepts apply regardless of what server-side language you're using.

Now that the referral ID has been passed to your server, we will send it as the client_reference_id parameter to the create Checkout Session API endpoint. Make sure to also pass customer_creation as 'always', otherwise we won't be able to associate a referral on Rewardful with a customer on Stripe.

checkout_params = {
success_url: '',
cancel_url: '',
payment_method_types: ['card'],
line_items: [{ price: 'price_ABCD1234', quantity: 1 }],
mode: 'payment',
customer_creation: 'always'

if params[:referral]
checkout_params[:client_reference_id] = params[:referral]


Note that client_reference_id is being assigned the value params[:referral] (sent from the browser) if it's present. Please see the Stripe documentation on client_reference_id for more details.

Did this answer your question?