Let your customers sell for you, and keep the affiliate ledger in your own account.
Referral Keeper is the open-source server behind a referral or affiliate program on Stripe: a tracking link, recurring commissions, refund and dispute clawbacks, a hold period and a payout CSV. First plan what a program would cost you below. It runs in your browser, so nothing is uploaded.
1. What would a referral program cost me?
| Month | Active | Revenue | Commission earned | Paid out so far | Still owed |
|---|
2. Make a link and the checkout snippet
Share link:
Add <script src="https://YOUR-SERVER/r.js" defer></script> to your site. Payment Links are tagged automatically. For Checkout Sessions you create, pass the code through:
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: "price_123", quantity: 1 }],
client_reference_id: ref, // from referralKeeper.clientReferenceId() in the browser, sent with your request
success_url: "https://example.com/thanks",
});
3. Run the server yourself
git clone https://github.com/Duncan-Haywood/fp-monorepo && cd fp-monorepo/ventures/referral-keeper
STRIPE_WEBHOOK_SECRET=whsec_... ADMIN_KEY=$(openssl rand -hex 16) \
PUBLIC_URL=https://refs.example.com SITE_URL=https://example.com \
PROGRAM_JSON='{"percent":25,"months":12,"holdDays":30,"minPayout":5000}' node server.mjs
Point a Stripe webhook at /webhook/stripe for checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid, charge.refunded, charge.dispute.created and charge.dispute.closed. It needs no Stripe API key. Add affiliates at /admin; each gets a private dashboard link. One-click Render deploy and Docker are in the README.
Questions
Why not use Rewardful, FirstPromoter or a Stripe app?
Hosted affiliate tools are polished and quick to set up, and some connect to Stripe in a few clicks. The trade-off is a monthly fee or a share of the revenue they track, and your affiliates and customer data living on their platform. Referral Keeper runs in your own account, reads only Stripe webhooks, and has no fee. It is leaner: no affiliate marketplace, no automatic payments to affiliates, one admin key. If a hosted tool already earns its fee for you, keep it.
How is a referral attributed to an affiliate?
A one-line script on your site stores the affiliate code from the link in a cookie on your own domain. Stripe Payment Links are tagged automatically; for Checkout Sessions you create, you pass the code as client_reference_id. When Stripe tells the server about the completed checkout, that customer belongs to the affiliate, and every later invoice for them earns commission until the window you set ends.
What happens on a refund or chargeback?
A refund reduces the commission in proportion. A dispute withholds it until the dispute closes in your favour. If the commission was already paid out, the affiliate's balance goes negative and the next commissions absorb it, so you are never forced to chase money back. New commission is also held for a number of days (30 by default) before it becomes payable.
Does it pay my affiliates?
No. It keeps the ledger and produces a payout CSV that you pay by bank transfer, PayPal, Wise or any other method, then you mark the payout paid. It never holds or moves money and never needs a Stripe API key, only the webhook signing secret.
Are there legal or tax things to know?
Yes. Affiliates generally must disclose the relationship when they promote you, and you may have tax-reporting duties for what you pay them depending on where you both live. This software is not legal or tax advice and you operate the programme.