Stripe Integration

Overview

The Stripe integration connects your Stripe account to Affihub via webhooks. When a referred customer completes a checkout session or pays an invoice, Affihub automatically creates a commission for the referring partner.

Prerequisites

• Affihub tracking script installed on your site
• A Stripe account with Checkout or Billing enabled
• Your Affihub Program ID and API Key (from Settings & Keys)

Step 1: Create the webhook endpoint

In your Stripe Dashboard:

1. Go to Developers → Webhooks
2. Click Add endpoint
3. Enter the URL:

https://api.affihub.com/webhooks/stripe?program_id=YOUR_PROGRAM_ID

4. Under Events to send, select:

   • checkout.session.completed
   • invoice.paid

5. Click Add endpoint

6. Copy the Signing Secret (starts with whsec_)

Step 2: Save the signing secret

In your Affihub provider dashboard:

1. Go to Settings
2. Paste the signing secret into the Stripe Webhook Secret field
3. Save

This allows Affihub to verify that incoming webhooks are genuinely from Stripe.

Step 3: Pass the referral at checkout

When creating a Stripe Checkout Session, include the partner's referral slug:

const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
 
app.post("/create-checkout", async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    mode: "payment",
    line_items: [
      {
        price: "price_xxx",
        quantity: 1,
      },
    ],
    success_url: "https://yoursite.com/success",
    cancel_url: "https://yoursite.com/cancel",
 
    // Pass the Affihub referral
    client_reference_id: req.body.affihub_ref || undefined,
  });
 
  res.json({ url: session.url });
});

On the frontend, read the referral from the tracking script:

const ref = window.AffiHub.getRef();
 
fetch("/create-checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    affihub_ref: ref?.ref || "",
  }),
});

Using metadata instead of client_reference_id

If you're already using client_reference_id for something else, you can pass the referral in metadata:

const session = await stripe.checkout.sessions.create({
  // ...
  metadata: {
    affihub_ref: req.body.affihub_ref || "",
  },
});

Affihub checks both client_reference_id and metadata.affihub_ref when processing webhooks.

Step 4: Subscriptions and invoices

For subscription-based products, Affihub also listens for invoice.paid events. To attribute subscription renewals:

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: "price_xxx" }],
  metadata: {
    affihub_ref: req.body.affihub_ref || "",
  },
});

When an invoice is paid, Affihub extracts the referral from:

1. The subscription's metadata.affihub_ref
2. The invoice line item metadata

How attribution works

When Affihub receives a checkout.session.completed webhook:

1. Verifies the Stripe signature using your webhook secret
2. Reads client_reference_id or metadata.affihub_ref
3. Looks up the partner by slug in your program
4. Evaluates your commission flow rules to determine the rate
5. Creates a commission with:
   • txn_amount_cents: The total payment amount
   • amount_cents: The calculated commission
   • status: pending
   • provider: stripe
   • provider_event_id: The Stripe event ID (for deduplication)

Deduplication

Each Stripe event has a unique ID (e.g., evt_xxx). Affihub stores this as provider_event_id and checks for duplicates before creating a commission. If Stripe retries a webhook delivery, no duplicate commission is created.

Testing with Stripe test mode

Stripe test mode webhooks work with Affihub. To test:

1. Set up the webhook endpoint as described above (Stripe sends test events to the same URL)
2. Create a test partner with slug test-partner
3. Use Stripe's test card (4242 4242 4242 4242) to complete a checkout with client_reference_id: "test-partner"
4. Check your Affihub dashboard for the new commission

Stripe Connect for payouts

Affihub can pay partners directly via Stripe Connect. See Payouts for setup details.