Stripe Integration

Overview

Refgrow integrates with Stripe to automatically track payments and calculate commissions for your affiliates.

• Automatic tracking of one-time payments and subscriptions
• Support for product-specific commission rates
• Support for affiliate-specific commission overrides
• Secure webhook implementation for real-time tracking
• Works with both Stripe Checkout Sessions and Payment Links

Setting Up Stripe Integration

Step 1: Connect Your Stripe Account

1. Go to your project's "Integration" tab
2. Select "Stripe Webhooks" as your tracking method
3. Enter your Stripe Secret Key (a restricted key is recommended)
4. Click "Connect Stripe"

Step 2: Choose Your User Flow

Select the appropriate user conversion flow for your business:

• Click → Signup → Purchase: Users create an account before making a purchase
• Click → Purchase: Users can purchase directly without signing up first
• Both: Your platform supports both flows

Passing Referral Codes to Stripe

For Stripe Checkout Sessions

When creating a checkout session on your server, pass the referral code in the metadata:

// Example (Node.js Server-Side)
const refCode = req.cookies.refgrow_ref_code; // Get code from cookie

const session = await stripe.checkout.sessions.create({
  // ... other session parameters
  metadata: {
    referral_code: refCode || null // Pass the code here
  }
});

For Stripe Payment Links

For payment links, there are two options:

Option 1: Automatic Processing with JavaScript

Add a special class to your payment links:

<a href="https://buy.stripe.com/xyz..."
   class="refgrow-stripe-payment-link">
  Buy Now
</a>

Call the helper function after the page loads:

// Call this once after the page loads
if (window.Refgrow) {
  Refgrow.processStripePaymentLinks();
}

Option 2: Programmatic Redirects

Redirect users with this helper function:

// Use this when you want to redirect a user to a payment link
if (window.Refgrow) {
  Refgrow.redirectToStripePaymentLink('https://buy.stripe.com/xyz...');
  // Don't use window.location.href = url; directly
}

Attribution Methods

Refgrow uses multiple methods to attribute a Stripe customer to an affiliate, checked in this priority order:

1. Coupon / Promotion Code Match

If the customer used a coupon code that matches an affiliate's coupon in Refgrow, the conversion is attributed to that affiliate. This is the most reliable method.

2. Checkout Session Metadata

Pass the referral code in the Stripe Checkout Session metadata:

const session = await stripe.checkout.sessions.create({
  // ... other options
  metadata: {
    referral_code: "AFFILIATE_CODE"
  }
});

3. Client Reference ID

Set the client_reference_id to the referral code when creating a Checkout Session:

const session = await stripe.checkout.sessions.create({
  client_reference_id: "AFFILIATE_CODE",
  // ... other options
});

4. Subscription Metadata

The referral code can also be passed in the subscription metadata.

5. Email Fallback

If none of the above methods match, Refgrow checks the referral_attributions table to see if the customer's email was previously attributed to an affiliate via the tracking script.

Commission Configuration

Default Commission Settings

Configure your default commission structure in your project settings:

• Commission Type: Percentage or Fixed Amount
• Commission Value: The percentage or fixed amount
• Commission Duration: Lifetime, First Purchase, or Limited Period

Product-Specific Commissions

Override commission rates for specific products:

1. Go to your project's "Integration" tab
2. Scroll to "Product-Specific Commissions"
3. Click "Add Product Commission"
4. Select a Stripe product and set its unique commission rate

Affiliate-Specific Overrides

Set custom commission rates for individual affiliates:

1. Go to your "Affiliates" tab
2. Find the affiliate you want to customize
3. Click "Manage Override"
4. Set a custom commission type and value

How It Works

Subscription Commissions

For subscription products, Refgrow tracks commissions on:

• Initial payment — commission on the first charge
• Recurring payments — optional recurring commissions on each renewal (configurable per-project)
• Upgrades — additional commission on the upgrade difference

Commission is automatically reversed on refunds and subscription cancellations.

Supported Webhook Events

Refgrow automatically listens for these webhook events:

• checkout.session.completed — When a purchase is completed
• invoice.paid — When a subscription invoice is paid
• customer.subscription.created — When a new subscription is created
• customer.subscription.updated — When a subscription is updated (plan changes, renewals)
• customer.discount.created — When a coupon is applied (for renewal tracking)
• charge.refunded — When a charge is refunded

Testing

1. Use Stripe's test mode and test API keys during development
2. Create a test affiliate in your Refgrow project
3. Make a test purchase with the affiliate's referral code or coupon
4. Verify the conversion appears in Refgrow with the correct commission
5. Use the Stripe CLI or webhook testing to replay events

Troubleshooting

Webhooks Not Working

1. Verify your Stripe API key is correctly set in your project settings
2. Check that the webhook endpoint was created (URL should match https://refgrow.com/webhook/stripe/{your-project-id})
3. Confirm all required events are enabled for the webhook
4. Check your Stripe dashboard for webhook delivery logs

Commissions Not Attributing

For "Click → Purchase" flow:

• Ensure the referral code is being passed to Stripe via metadata or client_reference_id
• Check that your tracking script is installed on all pages
• Verify the cookie is being set (check browser developer tools)

For "Click → Signup → Purchase" flow:

• Verify the customer email in Stripe matches the email used during signup
• Check that the referral attribution was created for the user
• Consider passing the referral code to Stripe as a more reliable method

Webhook Signature Verification Failing

• Ensure the webhook secret matches exactly. The raw request body must not be parsed by JSON middleware before signature verification.

Duplicate Conversions

• Refgrow deduplicates by Stripe event ID. If you see duplicates, check for multiple webhook endpoints pointing to the same project.

Next Steps

• Tracking Script — learn more about Refgrow's client-side tracking
• API Reference — manage affiliates and conversions programmatically
• Widget Customization — customize the affiliate dashboard