Integration Guide

How to Automate Referral Credits with Stripe + GrowSurf

Name: GrowSurf
Rating: 4.74 (47 reviews)
Author: GrowSurf

Set up automatic account credits for referrers using Stripe's customer balance and GrowSurf's referral engine.

Account credits are one of the most flexible referral rewards you can offer. Unlike percentage discounts or fixed coupons, credits accumulate in the referrer's Stripe customer balance and automatically apply to their next invoice. This makes them ideal for SaaS businesses that want to let users "earn" free usage through referrals.

This guide walks you through setting up automated referral credits using GrowSurf's webhook system and Stripe's Customer Balance Transactions API. You'll learn how to credit referrers instantly when a referral converts, track credit balances, and handle edge cases like refunds and churned customers. By the end, you'll have a fully automated credit-based referral reward system.

Integration Steps

Step 1: Plan Your Credit-Based Reward Structure

Before building, decide on your credit amounts and rules. Common structures include flat credits (e.g., $10 per referral), percentage-of-first-payment credits, or tiered credits that increase with more referrals.

Decide on credit amount per successful referral
Determine if credits should expire or roll over
Set a maximum credit balance cap if needed
Document your credit policy for transparency

Step 2: Configure GrowSurf Campaign with Webhook Reward

Set up your GrowSurf campaign to fire a webhook when referrals convert. Navigate to the Campaign Builder and configure the reward delivery method.

In Campaign > Rewards, select "Webhook" as the reward fulfillment method
Enter your webhook endpoint URL
Set the reward trigger (e.g., on conversion or after a waiting period)
Enable GrowSurf's fraud detection to prevent gaming

Step 3: Build the Credit Application Endpoint

Create a server-side endpoint that receives GrowSurf webhook events and applies credits to the referrer's Stripe customer balance.

Set up a POST endpoint (e.g., /api/referral-credit)
Validate the webhook signature from GrowSurf
Extract the referrer's email and referral metadata
Look up or create the Stripe customer record

Step 4: Create the Balance Transaction in Stripe

Use Stripe's Customer Balance Transactions API to add a negative balance (credit) to the referrer's account. Negative balances in Stripe are applied automatically to the next invoice.

Call stripe.customers.createBalanceTransaction() with a negative amount
Include a description that references the referral for audit trails
Store the transaction ID for reconciliation

Step 5: Set Up Credit Balance Monitoring

Implement monitoring to track outstanding credit balances and detect anomalies. This helps you forecast revenue impact and catch potential abuse.

Create a dashboard query that sums all referral credit balances
Set up alerts for unusually high credit accumulation
Track credit utilization rates (credits earned vs. credits used)

Step 6: Handle Edge Cases and Refund Scenarios

Build logic to handle situations where a referred customer refunds, churns within a trial period, or the referrer's account is closed.

Listen for Stripe charge.refunded events to claw back credits if needed
Implement a waiting period before granting credits (configurable in GrowSurf)
Handle cases where the referrer has no Stripe account yet

Code Snippets

// Apply referral credit to Stripe customer balance
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

async function applyReferralCredit(referrerEmail, creditAmount, referralId) {
  // Find or create the Stripe customer
  let customers = await stripe.customers.list({
    email: referrerEmail,
    limit: 1
  });

  let customer;
  if (customers.data.length === 0) {
    customer = await stripe.customers.create({
      email: referrerEmail,
      metadata: { source: 'growsurf_referral' }
    });
  } else {
    customer = customers.data[0];
  }

  // Create a negative balance transaction (credit)
  const transaction = await stripe.customers.createBalanceTransaction(
    customer.id,
    {
      amount: -creditAmount, // Negative = credit
      currency: 'usd',
      description: `Referral credit for referral ${referralId}`,
      metadata: {
        referral_id: referralId,
        source: 'growsurf'
      }
    }
  );

  return transaction;
}

// Webhook handler
app.post('/api/referral-credit', async (req, res) => {
  const { event, referrer, participant } = req.body;

  if (event === 'CAMPAIGN_REFERRAL_CONVERTED') {
    const transaction = await applyReferralCredit(
      referrer.email,
      1000, // $10.00 in cents
      participant.id
    );
    res.json({ success: true, transactionId: transaction.id });
  }
});

Tips

Use Metadata for Reconciliation

Always include GrowSurf referral IDs in Stripe balance transaction metadata. This creates a clear audit trail and makes it easy to reconcile credits with specific referrals during accounting reviews.

Implement a Credit Cap

Set a maximum credit balance to protect your revenue. Before applying new credits, check the customer's current balance and skip or reduce the credit if they've hit the cap. Communicate this cap clearly in your referral program terms.

Consider a Waiting Period

Use GrowSurf's reward delay feature to wait 7-14 days before issuing credits. This gives you time to verify the referred customer is legitimate and reduces fraud risk from self-referrals or low-quality sign-ups.

FAQ

How do Stripe customer balance credits work with invoices?

When a customer has a negative balance (credit) in Stripe, it's automatically applied to their next invoice. If the credit exceeds the invoice amount, the remaining balance carries forward to subsequent invoices. This happens automatically — no additional code is needed.

Can I set referral credits to expire after a certain period?

Stripe customer balance credits don't have built-in expiration. To implement expiry, you'll need to track credit creation dates in your database and create a scheduled job that reverses expired credits by creating positive balance transactions.

What happens if I need to reverse a referral credit?

Create a positive balance transaction for the same amount with a description noting the reversal reason. Use the original transaction's metadata to link the reversal to the original credit for clear accounting records.

GrowSurf for Startups Program

Startups get a 50% discount

GrowSurf Deals

Get $234k+ In Software Savings

LoyaltySurf

Reward Your Customers For Their Loyalty

Startup Growth Tactics Quiz

How to Automate Referral Credits with Stripe + GrowSurf

Integration Steps

Step 1: Plan Your Credit-Based Reward Structure

Step 2: Configure GrowSurf Campaign with Webhook Reward

Step 3: Build the Credit Application Endpoint

Step 4: Create the Balance Transaction in Stripe

Step 5: Set Up Credit Balance Monitoring

Step 6: Handle Edge Cases and Refund Scenarios

Code Snippets

Tips

Use Metadata for Reconciliation

Implement a Credit Cap

Consider a Waiting Period

FAQ

How do Stripe customer balance credits work with invoices?

Can I set referral credits to expire after a certain period?

What happens if I need to reverse a referral credit?

Unlock the power of word-of-mouth marketing anddeepen your bond with customers

Set up your refer a friend program with customer referral and affiliate program software that lowers your acquisition costs, increases customer loyalty, and saves you gobs of time.

Built for startups,scaled for unicorns

View GrowSurfCustomer Examples

Unlock the power of word-of-mouth marketing and
deepen your bond with customers

Built for startups,
scaled for unicorns

View GrowSurf
Customer Examples