# Stripe
## For Referral Programs
### Referral Trigger
#### Description
For referral programs, when you connect your Stripe account to your GrowSurf campaign and enable *Referral Trigger*, GrowSurf will automatically detect and trigger referrals on new Stripe charges.
GrowSurf will check if the Stripe customer's email address matches a GrowSurf participant's email address. If a match is found, then a referral will trigger, giving referral credit to the referrer and unlocking any rewards, if applicable.
Even if the Stripe customer's email address changes, GrowSurf will track those changes to ultimately ensure the referral trigger ties back to the referrer.
Here's how to set up Stripe referral triggers:
#### **How to Set Up**
{% hint style="warning" %}
**Important Note:** Unless your campaign is configured to add participants automagically ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LgbRcVrYaKYUhQVctKK%2F-LgbS62PrNqHiJm-qwdI%2FScreen%20Shot%202019-06-05%20at%207.42.50%20PM.png?alt=media\&token=85e064ce-4bac-4617-9481-f80215478d51)), you'll need to make sure you first call JavaScript [`growsurf.addParticipant()`](https://docs.growsurf.com/integrate/javascript-web-api/api-reference#add-participant) or REST API [`/POST Add Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#add-participant) to add new participants**.**
{% endhint %}
**Step 1**: In *Campaign Editor > 4. Options > Integrations*, click the *Connect to Stripe* button
**Step 2:** Once connected, GrowSurf will have *Referral Trigger* enabled by default.
**(Optional) Step 3:** You can add a referral trigger hold period by toggling the *Show advanced settings* section.
{% hint style="info" %}
**Note:** The referral trigger hold period is useful for preventing fraud and helps minimizes losses due to refunds and chargebacks. During this hold period, if there is a refund or chargeback, the referral trigger will be cancelled completely.
{% endhint %}
#### Stripe Metadata
GrowSurf will also update metadata for Stripe customers who trigger referrals.
| **Metadata Key** | **Description** | **Example** |
| ------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **GrowSurf Participant ID** | The GrowSurf participant ID of the Stripe customer who was referred | `xyz456` |
| **GrowSurf Participant URL** | The URL of the referred Stripe customer | `https://growsurf.com/dashboard/campaign/abc123/participant/xyz456/participant/xyz456` |
| **GrowSurf Referrer ID** | The ID of the participant who referred the Stripe customer | `hij789` |
| **GrowSurf Participant Referred By URL** | The URL of the participant who referred the Stripe customer | `https://growsurf.com/dashboard/campaign/abc123/participant/hij789` |
| **GrowSurf Participant Referred By Email** | The email address of the participant who referred the Stripe customer | `bob@loblaw.com` |
#### Test Mode
Our Stripe integration comes with a test mode that allows you to test triggering referrals without using live payments. When you toggle *Test Mode* on, GrowSurf will also process all test mode payments made in your Stripe account.
{% hint style="info" %}
**Using a Stripe Sandbox account?**
Instead of using test data from your live Stripe account, you can alternatively connect to your Stripe sandbox account. Simply toggle the *Test Mode* switch and you'll see a popup that lets you choose between connecting your sandbox account or just using test data from your live account.
{% endhint %}
{% hint style="warning" %}
**Important note:** When you go live with your campaign, please make sure to switch back to live mode. Otherwise, referral triggers will not be issued in live mode while test mode is enabled.
{% endhint %}
For more details on Stripe Testing, [see here](https://stripe.com/docs/testing).
#### Troubleshooting Tips
* When testing out the Stripe Referral Trigger integration, make sure to view participants' activity logs for details that can help you troubleshoot any issues.
* If you were expecting a referral to be triggered in live mode, double-check that you do not have test mode enabled.
* If your Stripe customer changes their email address and then makes a payment in Stripe (which triggers a referral), there needs to be at least a few minutes between those events, or else the referral trigger will not register. This is because GrowSurf relies on Stripe sending out a webhook event which notifies GrowSurf of the Stripe customer's new email address.
### Coupons/Credits
#### **Description**
When a GrowSurf participant unlocks a reward, apply a coupon or credit to a Stripe customer.
Even if the Stripe customer's email address changes, GrowSurf will track those changes to ultimately ensure the Stripe coupon/credit gets applied to the right Stripe customer.
#### How to Set Up
**Step 1:** In *Campaign Editor > 4. Options > Integrations*, click the *Connect to Stripe* button.
{% hint style="info" %}
You must first select a default currency for your GrowSurf campaign in order to use Stripe.\
\
Your default currency determines whether Stripe coupons or credits can be applied to your Stripe customers or subscriptions. For example, if your default currency is USD then the coupon or credit that you set up can only be redeemed for Stripe customers or subscriptions that are using USD.
{% endhint %}
**Step 2:** Once connected, click the *Coupons/Credits* tab and connect a reward(s) to Stripe by clicking the *Connect a Reward* button.
{% hint style="info" %}
**Note:** When you connect to Stripe, *Referral Trigger* will be enabled by default. If you are triggering referrals another way, disable the toggle in the *Referral Trigger* tab.
{% endhint %}
Click on either *Coupon* or *Credit.* If coupon is selected, enter the details of the coupon including the name, type, and discount. You can also click *Show advanced coupon* settings to view more customization settings.
{% hint style="info" %}
**Advanced feature tip: Issue different reward amounts by using dynamic rewards**
Dynamic rewards let you offer different reward values based on specific attributes of the referred friend (such as the pricing plan they signed up for) or referrer (such as their partner status).
For example, you can award $50 in credits to winners when their referral signs up for your base plan or $100 in credits when they sign up for a higher-costing plan.
[Learn more →](https://support.growsurf.com/article/357-how-to-set-up-dynamic-rewards)
{% endhint %}
{% hint style="info" %}
**Note:** By default, coupons are recommended. However, if you want rewards to be stackable (e.g, $10 off for every referred friend, 100% off for one month), you have two options:
1. Select "Coupon" and make sure you apply coupons to Subscriptions instead of Customers.
2. Alternatively, you can choose to apply a "Credit" (instead of "Coupon").
{% endhint %}
If credit is selected, enter the details of the credit including the description and credit amount, which is applied to the customer's balance every time this reward is unlocked.
Then hit Save. Now, anytime this reward is unlocked by a winning participant, a Stripe coupon or credit will also be applied to the Stripe customer or subscription associated with the GrowSurf participant email address.
{% hint style="info" %}
With double-sided rewards, you have full flexibility in choosing who gets the coupon or credit reward: (1) just the referrer, (2) just the referred person, (3) or both referrer and referred person.
{% endhint %}
Once you save the reward, you should see a green dot, indicating that the Stripe *Coupons/Credits* integration is enabled.
#### Stripe Metadata
GrowSurf will also update metadata for the Stripe coupon with information.
| **Metadata Key** | **Description** | **Example** |
| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **GrowSurf Campaign ID** | The unique ID of the GrowSurf campaign | `abc123` |
| **GrowSurf Participant ID** | The GrowSurf participant that unlocked the Stripe coupon | `xyz456` |
| **GrowSurf Participant URL** | The URL of the GrowSurf participant that unlocked the Stripe coupon | `https://growsurf.com/dashboard/campaign/abc123/participant/xyz456` |
| **GrowSurf Reward Description** | The description of the GrowSurf campaign reward | `Refer a friend and get 2 months free!` |
| **GrowSurf Participant Reward ID** | The unique ID of the participant's unlocked reward | `prew_hij630` |
#### Test Mode
Our Stripe integration comes with a test mode that allows you to test coupons/credits without using live coupons/credits. When you toggle *Test Mode* on, GrowSurf will apply coupons/credits only to your Stripe account in test mode. It is important to note that Stripe coupons/credits created in test mode will only apply to Stripe customers and Stripe Subscriptions that exist within your Stripe account when test mode is toggled on.
To enable test mode, toggle the *Test Mode* switch at the bottom-right, then connect a reward(s).
{% hint style="info" %}
**Using a Stripe Sandbox account?**
Instead of using test data from your live Stripe account, you can alternatively connect to your Stripe sandbox account. Simply toggle the *Test Mode* switch and you'll see a popup that lets you choose between connecting your sandbox account or just using test data from your live account.
{% endhint %}
Please note that the rewards you connect while *Test Mode* is enabled are completely separate from the rewards you connect while in live mode.
{% hint style="warning" %}
**Important note:** When you go live with your campaign, please make sure to switch back to live mode. Otherwise, coupons/credits will not be issued in live mode while test mode is enabled.
{% endhint %}
#### Troubleshooting Tips
If there is an issue with applying Stripe coupons or credits, GrowSurf will send out a notification email to the campaign owner. The issue will also be stated in the participant's detail page when you view their reward or when you view the participant's activity logs.
Here are some common reasons why there may be failures:
* The customer with the associated GrowSurf participant email address does not exist in Stripe (please make sure to check live or test mode depending on if you have toggled on Test Mode in the GrowSurf Stripe integration)
* If dynamic reward rules are enabled for the Stripe reward, there may have been no matching rule found.
* If you were expecting a coupon/credit to be applied in live mode, double-check that you do not have test mode enabled.
* If your Stripe customer changes their email address right before the Stripe reward gets applied, they may not receive it. This is because GrowSurf relies on Stripe sending out a webhook event which notifies GrowSurf of the Stripe customer's new email address, but if there is not at least a few minutes before the reward event, GrowSurf will not know about the Stripe customer's email change.
If there was a failure, you will need to manually issue the Stripe reward from your [Stripe dashboard](https://dashboard.stripe.com/dashboard/).
#### Other notes:
* Only companies based in the [following 135+ countries](https://stripe.com/docs/currencies) can use the Stripe coupons/credits integration.
* If you have manual reward approval enabled for your campaign: Stripe coupons/credits will only be issued to the winner(s) only after you approve the reward.
* If the referral was triggered recently (or if the reward was approved recently), please allow for a few minutes of server processing before viewing the participant's reward from your GrowSurf admin dashboard. During this time, the data displayed for the participant's reward may not be accurate.
### Upfront Discounts
The **Upfront Discount** feature lets you create a campaign-wide coupon that is instantly available to referred friends, before they make a purchase (e.g., "Get 20% off your first invoice"). This is useful for giving referred visitors a discount code they can apply at checkout via Stripe Payment Links or your own checkout flow.
#### How It Works
1. In the GrowSurf campaign editor, go to *1. Rewards and* create a **Double-Sided** reward. Then, enable **"Give the referred friend their reward upfront instead of after they complete the qualifying action"**. Save your changes.
2. Go to *4. Options > Integrations,* connect to Stripe, then click "Connect a Reward" and link your rewards. For your Double-Sided reward, select "Both the referrer and referred friend."
3. Save changes. GrowSurf will automatically create a coupon on your connected Stripe account.
4. When a referred visitor lands on your site, the promotion code is available via the GrowSurf JavaScript method [`growsurf.getUpfrontDiscount()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-upfront-discount).
5. When the referral triggers (e.g., the first-time purchase happens), only the **referrer** earns a reward. The referred friend's reward is not duplicated since it was already delivered upfront.
#### Applying the Upfront Discount
{% tabs %}
{% tab title="Stripe Payment Links" %}
## Stripe Payment Links
If you use [Stripe Payment Links](https://stripe.com/docs/payment-links), GrowSurf automatically appends the promotion code to your payment link URLs so the discount is pre-applied for referred visitors. They will see the discount applied at checkout.
{% hint style="warning" %}
**Important Note:** Make sure to enable "Allow promotion codes" in Stripe:
* [Open Stripe Payment Link settings](https://dashboard.stripe.com/payment-links)
* [Open Stripe Payment Link test settings](https://dashboard.stripe.com/test/payment-links)
{% endhint %}
{% endtab %}
{% tab title="JavaScript" %}
## JavaScript
Alternatively, if you are not using Stripe Payment Links you can retrieve the upfront discount using the JavaScript method [`growsurf.getUpfrontDiscount()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-upfront-discount) then apply it to your new referred customer:
```js
const discount = growsurf.getUpfrontDiscount('stripe');
if (discount) {
console.log(discount.promotionCode); // e.g., "GRSF-A1B2C3D4"
console.log(discount.couponId); // Stripe coupon ID
}
```
{% endtab %}
{% endtabs %}
#### Notes
* Upfront discount is only available for **Double-Sided** rewards with a referred friend coupon (not referrer rewards or credits).
* The upfront toggle is set on the reward in *Campaign Editor > 1. Rewards*. The Stripe integration settings will show the generated promotion code as read-only.
* If you change the referred friend coupon settings (e.g., discount amount) in the Stripe integration, the promotion code is automatically re-synced. (Behind the scenes, we delete the old coupon and create a new one. Your existing Stripe customers who already have the old coupon applied will remain unaffected).
* Upfront discounts cannot be used with [dynamic rewards](https://support.growsurf.com/article/357-how-to-set-up-dynamic-rewards). If you are using dynamic rewards, we recommend creating a single-sided reward and utilizing [`growsurf.validateReferrer()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#validate-referrer) then applying your own coupon code for referred visitors.
***
## For Affiliate Programs
#### Description
For affiliate programs, track payments and automatically generate commissions for affiliates.
When you connect your Stripe account to your GrowSurf campaign, GrowSurf will automatically detect Stripe payments and calculate commissions for affiliates. Gross-to-net taxes are factored in and if any refund/chargeback events happen, commissions will be adjusted accordingly.
Here's how to set up the Stripe integration for your affiliate program:
#### How to Set Up
{% hint style="warning" %}
**Important Note:** Unless your campaign is configured to add participants automagically ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LgbRcVrYaKYUhQVctKK%2F-LgbS62PrNqHiJm-qwdI%2FScreen%20Shot%202019-06-05%20at%207.42.50%20PM.png?alt=media\&token=85e064ce-4bac-4617-9481-f80215478d51)), you'll need to make sure you first call JavaScript [`growsurf.addParticipant()`](https://docs.growsurf.com/integrate/javascript-web-api/api-reference#add-participant) or REST API [`/POST Add Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#add-participant) to add new participants**.**
{% endhint %}
**Step 1**: In *Campaign Editor > 4. Options > Integrations*, click the *Connect to Stripe* button
Once connected, GrowSurf will track all payments, taxes, refunds, and chargebacks to ensure commissions are calculated and adjusted properly.
#### Stripe Metadata
GrowSurf will also update metadata for the \[referred] Stripe customers who made payments.
| **Metadata Key** | **Description** | **Example** |
| ------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **GrowSurf Participant ID** | The GrowSurf participant ID of the Stripe customer who was referred | `xyz456` |
| **GrowSurf Participant URL** | The URL of the referred Stripe customer | `https://growsurf.com/dashboard/campaign/abc123/participant/xyz456/participant/xyz456` |
| **GrowSurf Referrer ID** | The ID of the participant who referred the Stripe customer | `hij789` |
| **GrowSurf Participant Referred By URL** | The URL of the participant who referred the Stripe customer | `https://growsurf.com/dashboard/campaign/abc123/participant/hij789` |
| **GrowSurf Participant Referred By Email** | The email address of the participant who referred the Stripe customer | `bob@loblaw.com` |
#### Test Mode
Our Stripe integration comes with a test mode that allows you to test generating commissions without using live payments. When you toggle *Test Mode* on, GrowSurf will also process all test mode payments made in your Stripe account.
{% hint style="info" %}
**Using a Stripe Sandbox account?**
Instead of using test data from your live Stripe account, you can alternatively connect to your Stripe sandbox account. Simply toggle the *Test Mode* switch and you'll see a popup that lets you choose between connecting your sandbox account or just using test data from your live account.
{% endhint %}
{% hint style="warning" %}
**Important note:** When you go live with your campaign, please make sure to switch back to live mode. Otherwise, commissions will not be generated in live mode while test mode is enabled.
{% endhint %}
For more details on Stripe Testing, [see here](https://stripe.com/docs/testing).
#### Troubleshooting Tips
* Always make sure to view participants' activity logs for details that can help you troubleshoot any issues with commissions.
* If you were expecting a commission to be generated after a Stripe payment was made, but it was not:
* Double-check that you have the right Stripe account connected (the account ID looks something like `acct_1IVnArhWhW2lhRIA`).
* If you were expecting a commission to be generated in live mode, double-check that you do not have test mode enabled.
* If the currency of the payment does not match your GrowSurf campaign's currency, the commission will not be generated.
* If you see a different commission amount from what you expected, double-check the commission structure by viewing the details of the commission.
* For example: you may have an introductory rate that gets applied instead of the standard commission rate.
* Another example: if you have a maximum commission limit set in the campaign reward, the commission amount that was earned may reflect that.
* If your referred Stripe customer changes their email address and then makes a payment in Stripe (which generates the first commission), there needs to be at least a few minutes between those events, or else the referral trigger will not register. This is because GrowSurf relies on Stripe sending out a webhook event which notifies GrowSurf of the Stripe customer's new email address.
* If your Stripe customer changes their email address right before the Stripe reward gets applied, they may not receive it. This is because GrowSurf relies on Stripe sending out a webhook event which notifies GrowSurf of the Stripe customer's new email address, but if there is not at least a few minutes before the reward event, GrowSurf will not know about the Stripe customer's email change.
#### **Other Notes:**
* Only companies based in the [following 135+ countries](https://stripe.com/docs/currencies) can use the Stripe affiliate program integration.
* If the Stripe payment from the referred customer was made recently, please allow for a few minutes of server processing before viewing the affiliate's commission from your GrowSurf admin dashboard. During this time, the data displayed for the participant's commission may not be accurate.
%202025-11-07%20at%2012.41.34%20PM.png?alt=media&token=903d1558-abbf-4f0b-8441-eed57c3d6499)
%202025-11-07%20at%2012.42.39%20PM.png?alt=media&token=5e9442f0-0804-4bac-933a-9f9d2ca3cdab)
%202026-01-02%20at%202.06.09%20PM.png?alt=media&token=e58689e4-a0ae-40cb-9033-419b60600a2b)