Stripe Integration

Automatically track revenue and attribute it to the visitors who converted.

Overview

The Stripe integration connects your Stripe account to Ripples so you can:

• See revenue attributed to each visitor and their acquisition source
• Track charges, subscriptions, and invoices automatically
• Backfill historical payment data when you first connect
• Handle refunds (negative revenue events are created automatically)

Revenue events appear in the visitor timeline and contribute to each profile's lifetime revenue total.

Prerequisites

Before connecting Stripe, make sure you have:

1. Persist mode enabled — Ripples uses a cookie (_rpl_vid) to track visitors across sessions. This is the default behavior.
2. User identification — Call ripples.identify() when users sign in so we can match Stripe charges to visitor profiles by email.

// Call this after login / signup
ripples.identify({
  id: "user_123",
  email: "[email protected]",
  name: "Jane Doe",
  plan: "pro",
})

Create a Restricted API Key

We recommend using a restricted API key with minimal permissions rather than your secret key.

1. Go to Stripe Dashboard → API Keys
2. Click "Create restricted key"
3. Give it a name like Ripples Analytics
4. Set the following permissions to Read:

The Webhook Endpoints: Write permission allows Ripples to automatically create a webhook in your Stripe account to receive payment events in real-time.

5. Click "Create key" and copy the key (it starts with rk_live_ or rk_test_)

Connect in Settings

1. Open your project dashboard in Ripples
2. Click the Integrations link in the header
3. Find the Stripe card and click Connect
4. Paste your restricted API key and click Connect

Once connected, Ripples will:

• Create a webhook endpoint in your Stripe account automatically
• Begin importing your historical charges (backfill)
• Start receiving new payment events in real-time

Revenue Attribution

Ripples uses a 3-tier fallback to attribute each Stripe payment to a visitor:

Tier 1: Checkout Metadata (Best)

Pass the visitor ID directly in your Stripe Checkout session metadata. This gives the most accurate attribution because it directly links the payment to the browsing session.

// Next.js (Server-side)
import { cookies } from "next/headers"
import Stripe from "stripe"

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)

export async function createCheckout() {
  const cookieStore = await cookies()
  const visitorId = cookieStore.get("_rpl_vid")?.value

  const session = await stripe.checkout.sessions.create({
    metadata: { ripples_visitor_id: visitorId },
    // ... other checkout options
  })
}

// Vanilla JavaScript (Client-side)
// Get visitor ID from the Ripples SDK
const visitorId = ripples.getVisitorId()

// Send to your server when creating a checkout session
const res = await fetch("/api/checkout", {
  method: "POST",
  body: JSON.stringify({ visitorId }),
})

// Laravel (Server-side)
use Stripe\StripeClient;

$visitorId = $request->cookie('_rpl_vid');
// or from frontend: $request->input('visitorId')

$stripe = new StripeClient(config('services.stripe.secret'));

$session = $stripe->checkout->sessions->create([
  'metadata' => ['ripples_visitor_id' => $visitorId],
  // ... other options
]);

Tier 2: Email Matching (Automatic)

If Tier 1 metadata is not present, Ripples matches the Stripe customer email to a visitor profile. This works when you have called ripples.identify() with the user's email.

No extra setup needed — this happens automatically.

Tier 3: Customer ID (Returning Customers)

For subsequent payments, Ripples remembers the Stripe customer ID from previous attributions. If a customer was attributed once (via Tier 1 or 2), all future payments from that customer are automatically attributed to the same visitor.

Events Tracked

The following Stripe events are processed:

Historical Backfill

When you first connect Stripe, Ripples automatically imports all your historical charges and attributes them using the same 3-tier fallback. Active subscriptions are also synced to update visitor plan fields.

You can check the backfill status on the Integrations settings page. If needed, use the Re-sync button to clear and re-import all data.

Deduplication

Ripples automatically prevents duplicate revenue events:

• Each Stripe charge, invoice, and checkout session is tracked by its unique ID
• Webhook retries and backfill re-runs are automatically deduplicated
• If you use the Stripe integration, you do not need to send revenue events from the frontend SDK — Stripe handles it automatically

Disconnecting

To disconnect the integration, go to Integrations settings and click Disconnect on the Stripe card. You can choose to keep or remove the imported revenue data.