Stripe Integration

Connect your Stripe account to automatically track purchases, refunds, chargebacks, and coupon usage - no code changes required.

Benefits of Stripe Integration

Automatic Tracking:

• Purchases tracked automatically from Stripe payments
• Refunds automatically reverse commissions
• Chargebacks automatically handled
• Coupon codes automatically detected and attributed

Accurate Commissions:

• Calculated on net amount (after discounts)
• Handles complex pricing scenarios
• Supports subscriptions and one-time payments
• Processes in real-time

No Code Required:

• Set up once, works forever
• No manual tracking calls needed
• Handles all edge cases automatically

Setup Guide

Step 1: Navigate to Integration Page

1. Log in to your refVenue dashboard
2. Go to Integration in the sidebar
3. Find the "Stripe Purchase Tracking" section

Step 2: Connect Stripe Account

1. Click Connect Stripe Account
2. You'll be redirected to Stripe
3. Log in to your Stripe account
4. Authorize refVenue to access your account
5. You'll be redirected back to refVenue

Connection Status: Once connected, you'll see:

• ✓ Stripe Account Connected
• Account ID displayed
• Last webhook timestamp
• Disconnect option

Step 3: Test the Integration

1. Go to Links & Codes page
2. Generate a test referral link
3. Open link in incognito/private browser
4. Make a test Stripe purchase
5. Check Dashboard for the tracked conversion

How It Works

Automatic Attribution

When a customer makes a purchase through Stripe, refVenue:

1. Receives the webhook from Stripe 2. Extracts customer email from the payment 3. Looks for affiliate attribution (in priority order):

• Recent affiliate click (email match within cookie duration)
• Coupon code used at checkout 4. Creates conversion with accurate commission 5. Updates affiliate earnings in real-time

Coupon Detection

If a customer uses a Stripe coupon at checkout:

1. refVenue extracts the coupon code from the invoice
2. Looks up the coupon in the CouponCode table
3. Finds the affiliate who created it
4. Attributes the conversion to that affiliate
5. No prior click required!

Commission Calculation

Commissions are calculated on the net amount (what customer actually paid):

Example:

• Product price: $100
• Coupon discount: 20% ($20 off)
• Customer pays: $80
• Your commission (10%): $8 (calculated on $80, not $100)

This ensures affiliates are paid on actual revenue, not pre-discount amounts.

Refunds & Chargebacks

Refunds:

• Stripe sends charge.refunded webhook
• refVenue finds the conversion
• Marks as REFUNDED
• Reverses commission from affiliate earnings

Chargebacks:

• Stripe sends charge.dispute.created webhook
• refVenue finds the conversion
• Marks as CHARGEBACK
• Reverses commission
• May affect affiliate quality score

Supported Stripe Events

refVenue listens for these Stripe webhooks:

Purchase Events

• payment_intent.succeeded - One-time payments
• invoice.payment_succeeded - Invoices and subscriptions

Refund Events

• charge.refunded - Full or partial refunds

Chargeback Events

• charge.dispute.created - New chargeback
• charge.dispute.updated - Chargeback status changed

Attribution Logic

Priority System

When a purchase comes through Stripe:

Priority 1: Check for recent affiliate click

• Looks for email match in AffiliateClick table
• Within cookie duration window (default 30 days)
• If found, attributes to that affiliate

Priority 2: Check for coupon code

• Extracts coupon from Stripe invoice
• Looks up coupon in CouponCode table
• If found, attributes to coupon owner

No Match: Conversion not tracked

Cookie Duration

The "cookie duration" setting in your program determines the attribution window:

• 30 days = customer must click within 30 days of purchase
• 60 days = customer must click within 60 days of purchase
• etc.

Advanced Features

Subscription Handling

First Payment:

• Tracked as conversion
• Commission paid

Renewal Payments:

• Not tracked (by design)
• Prevents paying commission multiple times
• Only initial conversion counts

Why: Most affiliate programs pay commission only on first payment, not renewals.

Multiple Currencies

refVenue supports all Stripe currencies:

• Commissions calculated in payment currency
• Stored with currency code
• Displayed in affiliate dashboard

Test Mode

During development:

• Use Stripe test mode keys
• Test purchases won't create real conversions
• Switch to live mode when ready

Troubleshooting

Connection Failed

Check:

1. You're logged in to the correct Stripe account
2. You have admin access to the Stripe account
3. Your browser allows cookies/redirects
4. Try again in incognito mode

Conversions Not Tracking

Verify:

1. Connection status shows "Connected"
2. Purchase was in live mode (not test mode)
3. Customer email is included in Stripe payment
4. Customer had recent click OR used valid coupon
5. Program is active

Check webhook status:

• Last webhook timestamp should update on purchases
• If stuck, disconnect and reconnect

Refunds Not Processing

Ensure:

1. Refund is processed through Stripe dashboard
2. Original conversion exists in refVenue
3. Conversion is not already refunded
4. Webhook connection is active

Commission Incorrect

Common Issues:

• Too high: Might be calculating on gross instead of net
• Too low: Check commission rate in program settings
• Zero: Check if revenue_amount is being passed correctly

Best Practices

Single Connection

• Connect one Stripe account per program
• Don't share Stripe connections across programs
• Each program should have its own tracking

Webhook Health

• Monitor "Last webhook" timestamp
• Should update with each purchase
• If stuck for days, reconnect Stripe

Testing

Before going live:

1. Test in Stripe test mode
2. Verify conversions appear
3. Test refunds
4. Test coupon codes
5. Switch to live mode

Security

• Never share Stripe secret keys
• Use Stripe dashboard for refunds
• Review suspicious conversions
• Monitor quality scores

Metadata (Optional)

For more control, add refVenue metadata to your Stripe checkout:

const session = await stripe.checkout.sessions.create({
  // ... other fields
  metadata: {
    program_id: 'YOUR_PROGRAM_ID',
    // Optional: override auto-detection
    ref_code: 'SPECIFIC_AFFILIATE',
  }
});

When to use:

• You want to force specific affiliate attribution
• You're handling attribution separately
• You have custom logic

Most cases: Let refVenue auto-detect from email/coupon (easier and more accurate).

Comparison: Stripe vs Manual Tracking

Recommendation: If you use Stripe, use the integration. It's more accurate and requires less maintenance.

Alternative: Manual Tracking

If you don't use Stripe or need more control, use manual tracking:

• JavaScript Integration
• Server-Side Tracking
• Webhook API

Support

Having issues?

• FAQ
• Troubleshooting
• Contact Support