Adding Refindie to Your Website

Install tracking script and integrate with your payment system.

Integration Steps

1. Add the tracking script

Copy and paste the script below in the <head> section of your website. Script Parameters:

data-program-id - Your affiliate program ID (required)

<script
  async
  src="https://www.refindie.com/refindie.js"
  data-program-id="YOUR_PROGRAM_ID"
></script>

2. Get referral data

The script sets a global object with referral information:

refindie_metadata.program_id (string | number)
refindie_metadata.ref_code (string)
refindie_metadata.is_new_visit (boolean)

3. Send data during payment

Include referral data in your payment API calls to attribute commissions.

Integration Options

Option 1: Stripe Connect (Recommended)

Connect your Stripe account in Settings > Integration
Send window.refindie_metadata from your frontend to your server
Attach it as metadata on the Stripe object that matches your payment flow (see the table below)

Refindie listens to your Stripe events and records the commission automatically.

Supported Stripe payment flows

Your Stripe integration	Put the referral metadata on	Tracked
Checkout Session, one-time payment (`mode: 'payment'`)	the session `metadata`	✅
Checkout Session, subscription (`mode: 'subscription'`)	the session `metadata`	✅ first payment + renewals
Checkout with a free trial or a 100% coupon	the session `metadata`	✅ first paid invoice + renewals
Checkout with delayed payment methods (SEPA Debit, bank transfer…)	the session `metadata`	✅ once the payment succeeds
PaymentIntents API (Payment Element, Card Element, mobile SDKs)	the PaymentIntent `metadata`	✅
Subscriptions API (`stripe.subscriptions.create`, no Checkout)	the subscription `metadata`	✅ first payment + renewals
Stripe Invoicing (one-off invoices)	the invoice `metadata`	✅
Payment Links, Buy Button, Pricing Table	not possible (no dynamic metadata)	⚠️ affiliate promotion codes only, or use the Referral API
Charges API (legacy `stripe.charges.create`)	not supported	❌ use the Referral API

Affiliate promotion codes are detected automatically on Checkout Sessions and invoices, even without metadata.

Metadata format

Refindie reads two keys, program_id and ref_code:

metadata: {
  program_id: String(refindieMetadata.program_id),
  ref_code: refindieMetadata.ref_code,
}

Passing the whole window.refindie_metadata object as metadata works too. In the examples below, refindieMetadata is the value of window.refindie_metadata sent by your frontend.

Checkout: one-time
Checkout: subscription
PaymentIntent
Subscription API
Invoice

const session = await stripe.checkout.sessions.create({
  // ... your items and config
  mode: 'payment',
  metadata: {
    program_id: String(refindieMetadata.program_id),
    ref_code: refindieMetadata.ref_code,
  },
});

const session = await stripe.checkout.sessions.create({
  // ... your items and config
  mode: 'subscription',
  metadata: {
    program_id: String(refindieMetadata.program_id),
    ref_code: refindieMetadata.ref_code,
  },
});

Renewals are attributed automatically through the subscription ID. subscription_data.metadata is also accepted, but the session metadata is preferred.

// Payment Element, Card Element, mobile SDKs…
const paymentIntent = await stripe.paymentIntents.create({
  amount: 5000,
  currency: 'eur',
  automatic_payment_methods: { enabled: true },
  metadata: {
    program_id: String(refindieMetadata.program_id),
    ref_code: refindieMetadata.ref_code,
  },
});

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: 'price_xxx' }],
  metadata: {
    program_id: String(refindieMetadata.program_id),
    ref_code: refindieMetadata.ref_code,
  },
});

const invoice = await stripe.invoices.create({
  customer: customerId,
  metadata: {
    program_id: String(refindieMetadata.program_id),
    ref_code: refindieMetadata.ref_code,
  },
});

Put the metadata on the object you create. Stripe does not copy metadata between objects: the metadata of a Checkout Session does not appear on its PaymentIntent, and the metadata of a PaymentIntent does not appear on a subscription. Refindie knows where to look for each flow listed above.

Professional payment processing
Commission tracking via Stripe metadata
Payment history and manual payout verification

Option 2: Referral API

Use the server-to-server endpoint when you use a custom payment provider or want to record a referral manually.

Endpoint: POST /api/referral
Headers: x-api-key: <YOUR_PROGRAM_API_KEY>
Body (JSON):
- ref_code (string)
- program_id (string | number)
- spent_amount (number, in cents)
- currency (string, e.g. “USD”)
- transaction_id (string, unique)

await fetch("/api/referral", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.NEXT_PUBLIC_REFINDIE_API_KEY!,
  },
  body: JSON.stringify({
    ref_code: window.refindie_metadata.ref_code,
    program_id: window.refindie_metadata.program_id,
    spent_amount: 5000, // amount in cents
    currency: "USD",
    transaction_id: "order_12345", // unique idempotency key
  }),
});

Implementation Examples

React Component (Next.js)

"use client";

const CheckoutButton = () => {
  const handleCheckout = async () => {
    try {
      const response = await fetch("/api/checkout", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          amount: 1000,
          currency: "eur",
          metadata: window.refindie_metadata, // ⭐️ Referral data
        }),
      });

      const { url } = await response.json();
      if (url) window.location.href = url;
    } catch (error) {
      console.error("Error:", error);
    }
  };

  return <button onClick={handleCheckout}>Pay Now</button>;
};

API Route (app/api/checkout/route.ts)

import { NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-06-20",
});

export async function POST(req: Request) {
  try {
    const { amount, currency, metadata } = await req.json();

    const session = await stripe.checkout.sessions.create({
      line_items: [
        {
          price_data: {
            currency: currency,
            product_data: {
              name: "Product",
            },
            unit_amount: amount,
          },
          quantity: 1,
        },
      ],
      mode: "payment",
      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/cancel`,
      metadata: metadata, // ⭐️ Referral data
    });

    return NextResponse.json({ url: session.url });
  } catch (error) {
    return NextResponse.json({ error: "Payment error" }, { status: 500 });
  }
}

AI Assistant Prompt

Copy this prompt into your AI assistant to implement this feature:

I need to integrate the Refindie affiliate tracking system into my website.

Here's what I need to implement:

1. Add the tracking script to my website's <head> section:
<script async src="https://www.refindie.com/refindie.js" data-program-id="YOUR_PROGRAM_ID"></script>

2. In my checkout/payment flow, send window.refindie_metadata to my server and attach { program_id, ref_code } as Stripe `metadata` on the object my server creates:
- Stripe Checkout: the Checkout Session `metadata` (not only payment_intent_data)
- PaymentIntents API / Payment Element: the PaymentIntent `metadata`
- Subscriptions API without Checkout: the subscription `metadata`
- Stripe Invoicing: the invoice `metadata`

Example implementation for payment:
```javascript
const handlePayment = async () => {
  const response = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: 1000,
      currency: 'eur',
      metadata: window.refindie_metadata // Include affiliate data
    })
  });
}
```

Please implement this affiliate tracking integration on my website, making sure the referral data is properly passed to my payment system.

Tips and Help

💡 Important Tips

Add the script to all your pages to never miss a referral
Referral data is available as soon as the script is loaded
Test the integration in development mode before production
Subscriptions: The first payment is tracked via the metadata (checkout session or subscription). Renewal payments are tracked automatically using the subscription ID, no extra work needed
Free trials: The commission is recorded on the first paid invoice, not when the trial starts
One payment, one commission: Refindie deduplicates on the Stripe invoice ID (or PaymentIntent ID for one-time payments). Don’t also call the Referral API for a payment that already goes through Stripe Connect

✅ Verification

To verify that the integration works, open your browser console and type window.refindie_metadata. You should see the referral data. After a test payment, open the object you created in your Stripe dashboard (Checkout Session, PaymentIntent, subscription or invoice) and check that its metadata contains program_id and ref_code.

🔎 Troubleshooting

I see a payment_intent.succeeded event without Refindie metadata. If you use Stripe Checkout, this is expected: Stripe does not copy the session metadata to the PaymentIntent. Check the checkout.session.completed event instead. If there is no checkout.session.completed event, you are using the PaymentIntents API directly: put the metadata on the PaymentIntent. The commission is missing for a subscription with a free trial. It is recorded when the first invoice is paid, at the end of the trial. The commission is missing for a SEPA or bank transfer payment. It is recorded once Stripe confirms the payment, which can take a few days.

Support

If you encounter any difficulties, contact us at contact@refindie.com or consult our documentation.

Email: contact@refindie.com
Check our Program Creation guide

For Creators

API

For Affiliates

Adding Refindie to Your Website

Adding Refindie to Your Website

Integration Steps

1. Add the tracking script

2. Get referral data

3. Send data during payment

Integration Options

Option 1: Stripe Connect (Recommended)

Supported Stripe payment flows

Metadata format

Option 2: Referral API

Implementation Examples

React Component (Next.js)

API Route (app/api/checkout/route.ts)

AI Assistant Prompt

Tips and Help

💡 Important Tips

✅ Verification

🔎 Troubleshooting

Support

​Adding Refindie to Your Website

​Integration Steps

​1. Add the tracking script

​2. Get referral data

​3. Send data during payment

​Integration Options

​Option 1: Stripe Connect (Recommended)

​Supported Stripe payment flows

​Metadata format

​Option 2: Referral API

​Implementation Examples

​React Component (Next.js)

​API Route (app/api/checkout/route.ts)

​AI Assistant Prompt

​Tips and Help

​💡 Important Tips

​✅ Verification

​🔎 Troubleshooting

​Support

Adding Refindie to Your Website

Integration Steps

1. Add the tracking script

2. Get referral data

3. Send data during payment

Integration Options

Option 1: Stripe Connect (Recommended)

Supported Stripe payment flows

Metadata format

Option 2: Referral API

Implementation Examples

React Component (Next.js)

API Route (app/api/checkout/route.ts)

AI Assistant Prompt

Tips and Help

💡 Important Tips

✅ Verification

🔎 Troubleshooting

Support