Stripe

Refport's Stripe integration listens to your Stripe webhook events and attributes sales to referral partners automatically whenever a refp_id click ID is present. There's no need to write your own webhook handler or call track.sale() manually for Stripe payments.

How it works

1. You connect your Stripe account in the Refport dashboard
2. Refport receives Stripe webhook events (checkout.session.completed, invoice.paid, etc.)
3. The webhook handler reads the click ID from session metadata or client_reference_id and records the sale
4. The partner's commission is calculated and queued for payout

Connect your Stripe account

Go to Settings → Integrations → Stripe in the Refport dashboard and click Connect. This authorises Refport to receive your Stripe webhook events via Stripe Connect.

Refport automatically registers for the required events:

• checkout.session.completed
• invoice.paid
• charge.refunded
• customer.subscription.created / deleted
• customer.created / updated

Passing the click ID to Stripe

There are three ways to pass referral attribution data to Stripe, depending on your setup.

Option 1 — Session metadata (recommended)

When creating a Checkout session in your code, add refportClickId and refportExternalCustomerId to the session metadata. This is the simplest approach and leaves client_reference_id free for your own use.

import Stripe from 'stripe';
import { getClickIdFromRequest } from 'refport';

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

async function createCheckoutSession(req: Request, user: User, priceId: string) {
  const clickId = getClickIdFromRequest(req);

  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/pricing',
    metadata: {
      refportExternalCustomerId: user.id,
      refportClickId: clickId ?? undefined,
    },
  });

  return session;
}

Option 2 — client_reference_id

You can also set client_reference_id directly with the refp_id_ prefix. This is useful if you prefer not to use metadata or need backward compatibility.

const session = await stripe.checkout.sessions.create({
  /* ...your params... */
  client_reference_id: clickId
    ? `refp_id_${clickId}`
    : undefined,
});

Attribution fallback chain

Refport resolves the click ID in this order:

1. refportExternalCustomerId in session metadata → find existing customer
2. refp_id_ prefix in client_reference_id → extract click ID directly
3. refportClickId and refportExternalCustomerId in Stripe customer metadata → fallback from previous interactions
4. Customer email → match against known Refport customers

Recurring subscriptions

For subscription renewals, Refport automatically handles invoice.paid events. The click ID is carried forward from the original checkout session via the Stripe customer record — you don't need to pass it again on each renewal.

Refunds

When Stripe fires a charge.refunded event, Refport automatically voids the corresponding sale commission. No additional configuration is needed.

Free trials

When a subscription is created with a trial period (customer.subscription.created with status: trialing), Refport tracks this as a lead event rather than a sale, attributing the trial start to the referring partner.

Testing the integration

Use Stripe's test mode to verify the integration end-to-end:

1. Connect a Stripe test account in Refport's dashboard (separate from your live account)
2. Use Stripe's test card 4242 4242 4242 4242 to complete a checkout
3. Check Conversions in the Refport dashboard — the sale should appear within seconds

The Refport dashboard distinguishes between live and test events so test data doesn't pollute your production analytics.