Stripe Integration Install Guide
Referral SaaSquatch's Stripe integration uses Stripe Connect to automatically track referrals and apply discounts to subscriptions. This guide will walk you through how to set up this integration.
🔗 Connect Stripe
The first step is granting your SaaSquatch Account access to your Stripe Account's Live and Test modes using Stripe Connect.
Test mode vs. live mode - Your Referral SaaSquatch program provides both a live and test mode. This test mode can be used in conjuction with Stripe's Test Mode to test payments, subscriptions, and adding user before deploying to your production environment.
To authorize your Referral SaaSquatch Live and Test tenants with the respective Stripe Account Live and Test modes:
- Head to the Install tab under Implementation in your Portal.
Note: Make sure that you are keeping track of whether you are connecting your Live or Test tenant.
- Click [Authorize] under Stripe API Key and follow the prompts to login to your Stripe account. This will automatically fill in the necessary API key.
- Repeat the same process for both your live and test accounts.
🔗 Install squatch.js
Making use of our squatch.js library will allow you to surface a gorgeously rendered referral widget to your users either on your website or in your app. Through this widget your users will be able to seamlessly refer their friends.
To get up and running follow the squatch.js install guide to place the widget on your page.
🔗 Integration Flow
In order to utilize the Referral SaaSquatch integration with Stripe it is important to be mindful of the correct order of operations for successfully completing the referral flow from a trial to a paid referral.
The supported Referral SaaSquatch Stripe integration flow is:
- Make sure that the Referrer is registered in Stripe with a valid credit card and plan selected
- Create an account for the Referred User in Stripe
- Add a valid credit card to the Referred User’s Account in Stripe
- Create a Referral SaaSquatch account for the Referred User
- Include their
payment_provider_idfrom Stripe (listed as "ID" under Customer Details)
- Attribute referral (the widget should automatically pick up the referral cookie)
- Update Referred User in Stripe with subscription to a plan and RS Referral Code as a Stripe Coupon.
Note: You only need to add the referral code as a coupon for the referred user's new subscription. Use squatch.js autofill to read the tracking cookie and pick up the referral code.
Referrers will get credit for inviting their friends as line-items automatically applied to their invoices every month.
Result: Referral converted to paid, rewards fulfilled in Stripe, rewards redeemed in Referral SaaSquatch.
🔗 Key Considerations:
- The conversion process may take time to propagate from Stripe to Referral SaaSquatch depending on the load on Stripe's system and the frequency of them sending out updates.
- Discounts or credits being applied to a user’s stripe invoice should have an
RS_appended at the beginning.
- Attempting to convert a referral using
account_status: PAIDin your squatch.js calls will have no effect when your program is configured for a payment provider integration. Only a non-zero, non-trial subscription applied to a customer's current or pending invoice will convert the referral and release the referrer reward.
- The reward for the referrer (generated once the referral is converted) is applied as a line item on a pending or existing invoice. This due to Stripe’s limitations on how account credits can be applied to customers. Stripe only allows account credits to be applied as line items, and line items can only be applied to invoices. In this way Stripe has designed invoices to only be used with subscriptions.
- Single charges in Stripe are processed independently of other activity on the account (including existing and pending invoices). This means that there is no way for us to interact with single charge transaction to apply any account credit before it is processed.
🔗 Dollar Credit Rewards
Looking to run a referral program with Stripe as your payment provider and Dollar Credit rewards?
This reward type is currently in Beta for our integration with Stripe. If you are interested in using this type of reward with your Stripe Referral SaaSquatch program please contact support to find out more.
🔗 Arbitrary Rewards
Looking to run a referral program with Stripe as your payment provider and an arbitrary reward type (like points, free time, foo credits)?
Stripe only supports credits in a single specified currency. Anything beyond that (arbitrary rewards) will not be recognized by Stripe.
If you are interested in running a Referral SaaSquatch referral program with arbitrary rewards (like points, free time, foo credits) please take a look at our API referral programs. API programs are extremely flexible and support a wide range of reward types, including Percentage Discount, Dollar Credit, Free Time, and Points. Please checkout our docs on API programs and our guides for each of these reward types.
🔗 That's it!
Check out our Common Pitfalls Guide.