DEV Community: Mihir kanzariya

What on_behalf_of actually changes on a Stripe destination charge (and what it does not)

Mihir kanzariya — Wed, 29 Jul 2026 18:57:07 +0000

I gave someone bad advice about this in a comment three weeks ago. They were about to ship it. Here is the correction, and the full picture of what the parameter actually does.

The claim I made was that adding on_behalf_of to a destination charge would let each connected account own its own disputes. That is wrong. It is a comfortable kind of wrong, too, because almost everything else about on_behalf_of does point in that direction.

What on_behalf_of genuinely changes

Set on_behalf_of to a connected account on a destination charge and Stripe treats that account as the settlement merchant. Per Stripe's Connect charges documentation, it:

Settles in the connected account's country. Stripe "settles charges in the country of the specified account to minimise declines and avoid currency conversions."
Prices with that country's fee structure. It "uses the fee structure for the connected account's country."
Shows their statement descriptor, not yours.
Shows their address and phone on the customer's statement when the two accounts are in different countries.
Pays out on their schedule. Stripe "pays out a connected account, depending on the days specified in its delays_days setting."

That is a real change in who the customer thinks they paid, and a real change in the economics of the charge. If your connected accounts sit in other countries, both the settlement currency and your per-transaction cost move.

What it does not change

Dispute liability.

For destination charges, and for separate charges and transfers, with or without on_behalf_of, Stripe's disputes documentation is explicit: "Stripe debits dispute amounts and fees from your platform account." You recover by reversing the transfer to the connected account.

Only full direct charges, created with the Stripe-Account header, move dispute liability onto the connected account.

So the presentation moves and the money does not. The customer sees the connected account's name on their statement, the connected account's country determines settlement, and then a chargeback lands on your platform balance anyway. Those two facts sit next to each other in the docs and it is easy to read the first and assume the second.

The capability cost nobody mentions

on_behalf_of is not free on the onboarding side. Stripe's account capabilities documentation states that "to enable connected accounts to accept a payment method for direct charges or charges with on_behalf_of, you must request that payment method's capability for those accounts."

So a plain destination charge needs transfers. A destination charge with on_behalf_of needs the payment method capability too, which for cards means card_payments, and card_payments requires transfers as a prerequisite. With transfers alone, your platform processes the charge.

In practice that means more verification for every connected account you onboard. If you are weighing on_behalf_of for presentation reasons, that is the bill.

The cross-border trap worth knowing before you ship

This one costs real money and it is easy to miss.

When a dispute arrives on a destination charge, the instinct is to reverse the transfer immediately and get your money back from the connected account. On cross-border transfers, do not.

Stripe's guidance: "Retransferring a previous reversal is subject to cross-border transfer restrictions, meaning you might have no means to repay your connected account. Instead, wait to recover disputed cross-border payment transfers for destination charges with on_behalf_of until after a dispute is lost."

Reverse early, win the dispute, and you can end up unable to send the money back.

The short version

	destination charge	with `on_behalf_of`	direct charge
statement descriptor	platform	connected account	connected account
settlement country and fees	platform	connected account	connected account
dispute liability	platform	platform	connected account
capability needed	`transfers`	`card_payments`	`card_payments`

If what you want is for partners to look like the merchant, on_behalf_of does that. If what you want is for partners to carry the chargeback risk, it does not, and you need direct charges.

I conflated those two for three weeks. Worth checking which one you actually need before the first dispute arrives and tells you.

Multi-currency affiliate commissions on Stripe: which amount do you actually owe?

Mihir kanzariya — Wed, 29 Jul 2026 02:03:26 +0000

If your customers pay in their own currency and you pay affiliates in yours, every payment carries two different amounts. Pick the wrong one and every commission you calculate is quietly wrong.

Two amounts, two currencies

Stripe calls the currency the customer is charged in the presentment currency, and the currency that lands in your account the settlement currency. When they differ, Stripe converts, and the conversion is where commission math goes wrong.

The invoice tells you what the customer paid. The balance transaction tells you what you actually received.

// invoice.paid
const invoice = event.data.object;
invoice.currency;      // presentment: what the customer was charged in
invoice.amount_paid;   // presentment amount, smallest currency unit

// Resolve the charge for this invoice. The field name depends on your API
// version (older versions expose invoice.charge, newer ones invoice.payments),
// so read it from your own version rather than copying a field name.
const charge = await stripe.charges.retrieve(chargeId, {
  expand: ['balance_transaction'],
});

const bt = charge.balance_transaction;
bt.currency;       // settlement: your account currency
bt.amount;         // settled, before Stripe's fee
bt.net;            // settled, after Stripe's fee
bt.exchange_rate;  // the rate used for THIS payment

Most commission code reaches for invoice.amount_paid, because it is right there in the webhook payload. On a single-currency account that is fine. The moment a customer pays in EUR and your account settles in USD, amount_paid is a number in a currency you never received.

Decide what the commission is a percentage of

There are two defensible answers, and you have to pick one deliberately.

A percentage of what the customer paid. Stable from the affiliate's side: the same sale always earns the same commission in the customer's currency. You absorb the exchange rate movement.

A percentage of what you received. Stable from your side: you never pay out more than a fixed share of money you actually hold. The affiliate's commission moves with the rate, and you have to explain that.

Neither is wrong. Shipping without deciding is, because then the code picks for you, and it picks whichever field was easiest to reach.

The refund trap

This is the part that catches people out.

When a currency-converted payment is refunded or disputed, Stripe converts back at the current rate, not the rate of the original charge. From Stripe's documentation on conversions for disputes and refunds:

Exchange rates fluctuate with the market, so the rate used during the payment can differ from the rate used when a dispute or refund occurs.

Their own worked example: a 60 USD payment at 0.88 EUR per USD settles as 52.80 EUR. If the rate is 0.86 when the refund lands, only 51.60 EUR comes back out of your balance. The customer still gets a full refund in their currency. You carry the difference.

So if you claw back a commission by recomputing it at today's rate, the reversal will not match what you originally recorded. A few hundred refunds later, that is a reconciliation gap nobody can explain.

Store the numbers, not just the percentage

The fix is boring and it holds up. On every commission row, write down enough that you never have to re-derive anything.

create table commission (
  id                   bigserial primary key,
  affiliate_id         bigint not null,
  invoice_id           text   not null,

  -- what the customer paid
  presentment_amount   bigint not null,
  presentment_currency text   not null,

  -- what you actually received
  settled_amount       bigint not null,
  settled_currency     text   not null,
  exchange_rate        numeric,
  balance_transaction  text,

  -- what you owe, frozen at calculation time
  commission_amount    bigint not null,
  commission_currency  text   not null,
  basis                text   not null,   -- 'presentment' or 'settled'

  created_at           timestamptz not null default now()
);

basis is the column that saves you. A year from now, when someone asks why two commissions on identical-looking sales came out different, the row says which side of the conversion it was calculated from.

And on a refund, reverse the stored commission_amount. Do not recompute it. The number you owed is the number you un-owe, wherever the rate has moved since.

One sentence for your program terms

If you pay affiliates in their local currency, there is a second conversion between you and them, so the amount landing in their bank will not always match the number in your dashboard. Say that in the terms in one sentence.

It costs nothing to disclose, and it prevents the support email that opens with "your dashboard says 40 and I received 38."

Self-referral and coupon leaks: the affiliate fraud checks worth building on Stripe

Mihir kanzariya — Tue, 28 Jul 2026 07:21:11 +0000

Affiliate fraud in a small SaaS program is rarely sophisticated. It is usually one of two things: someone buying through their own link to pocket the commission on their own subscription, or an affiliate's coupon ending up on a deals aggregator where it converts people who were already going to buy.

Neither one looks like fraud in your dashboard. Both look like growth.

These are the checks worth wiring in before the program gets big enough for it to hurt.

Self-referral: match on the card, not the email

Email matching is the obvious check and the easiest to beat. Anyone who wants the commission will use a second address.

Stripe gives you something harder to fake. Every PaymentMethod carries card.fingerprint, which stays the same for the same physical card even across different customers.

// on invoice.paid, before you write the commission row
const invoice = event.data.object;
const pm = await stripe.paymentMethods.retrieve(
  invoice.default_payment_method,
  { expand: ['card'] }
);

const fp = pm.card?.fingerprint;
if (fp && fp === affiliate.cardFingerprint) {
  return holdCommission(invoice, 'self_referral:card_match');
}

This needs the affiliate's fingerprint on file, which you have if they are also a paying customer. If they are not, fall back on cheaper signals and treat them as a score rather than a verdict:

Normalized email match (strip dots and +tags on Gmail before comparing)
Same billing postal code and same last4
Signup IP matching the IP recorded on the referral click
Under 60 seconds between the click and checkout

Any one of those alone is noise. Two or three stacking up on an affiliate's first ever conversion is worth a human look.

Coupon leaks: compare redemptions to clicks

If you hand affiliates a coupon code as well as a link, the code will eventually escape onto a deals site. Then you are paying recurring commission on customers who found you through Google and searched for a discount on the way to checkout.

The signal is a redemption count with no relationship to the affiliate's traffic.

const clicks = await countClicks(affiliate.id, last30Days);
const redemptions = await countRedemptions(affiliate.couponId, last30Days);

// an affiliate sending real traffic converts a fraction of their clicks
if (redemptions > 10 && redemptions / Math.max(clicks, 1) > 1) {
  flag(affiliate, 'coupon_leak');
}

An affiliate with 300 redemptions and 20 clicks is not sending you anyone. Their code is just loose on the internet.

Cookie stuffing: heavy clicks, dead conversion

This one runs the other direction. Someone loads your referral URL in a hidden iframe or an image tag, so every visitor to their site gets tagged, and they collect on whoever was going to convert anyway.

It shows up as click volume far above your program norm with a conversion rate far below it, usually concentrated in a couple of referrer domains that are not real content pages. Log the Referer header and user agent on every click and you can spot it in a single query.

Hold the commission, do not delete it

The mistake I would avoid: auto-rejecting on a flag. False positives happen, and an affiliate who loses a legitimate commission to your fraud rule will tell people about it.

Mark the commission pending with a reason instead, keep a normal payout hold window (30 days covers most monthly plans), and review the flagged ones by hand. At small volume there will not be many.

I build Referralful, affiliate software for SaaS built on Stripe, so I spend a lot of time in this corner of the API. The checks above are worth thinking through whatever you run your program on, including a homegrown one.

What have you actually seen get abused in your program?

Proration and plan changes: what does your affiliate actually earn when a customer upgrades mid-cycle?

Mihir kanzariya — Mon, 27 Jul 2026 06:53:04 +0000

If you run an affiliate program on top of Stripe, the happy path is easy. A customer signs up for $29/mo through an affiliate link, you pay 30% recurring, everyone's happy. Then the customer upgrades to a $99/mo plan on day 12 of their billing cycle, and your commission math quietly breaks.

The bug is almost always the same: someone sums invoice.amount_paid and multiplies by the commission rate. That number is wrong the moment proration enters the picture. Here's why, and how to compute the commission correctly from the invoice line items.

What Stripe actually does on an upgrade

Say the customer is on a $29/mo plan, 30-day cycle, and upgrades to $99/mo on day 12. Eighteen days are left. Stripe doesn't charge a fresh $99. It creates an immediate invoice with two proration line items:

A credit for the unused time on the old plan: 18/30 x $29 = -$17.40 (amount: -1740)
A charge for the remaining time on the new plan: 18/30 x $99 = +$59.40 (amount: 5940)

Net on that invoice: $42.00. That's what the customer pays today. At the next cycle they pay the full $99.

So what should the affiliate earn on this proration invoice? Not 30% of $99. Not 30% of $29. Thirty percent of the net commissionable amount you actually collected, which is $42.00, so $12.60. If you paid on amount_paid you'd happen to get this one right, but downgrades produce a net-negative proration invoice with amount_paid of 0 and a customer credit balance, and that's where naive summing falls apart.

Sum the line items, not the invoice total

The reliable source of truth is invoice.lines.data. Each line carries an amount (in the smallest currency unit, can be negative), a proration boolean, a currency, and a period. Sum the amounts and you get the subtotal, with negative proration credits already netted out.

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

// Returns the net commissionable amount in the smallest currency unit.
// Negative proration lines subtract automatically.
function commissionableAmount(invoice) {
  let net = 0;
  let currency = null;

  for (const line of invoice.lines.data) {
    // Skip pure tax-only lines if you don't pay commission on tax.
    // Line amounts are pre-tax subtotal contributions.
    net += line.amount;

    if (currency && line.currency !== currency) {
      throw new Error(`Mixed currencies on invoice ${invoice.id}`);
    }
    currency = line.currency;
  }

  return { amount: net, currency };
}

Note the currency guard. Stripe won't normally mix currencies on one invoice, but if you sum blindly across a customer's history you can end up adding cents to euros. Keep commission ledgers per currency and convert at payout time, not before.

The webhook handler

Compute commission on invoice.paid, so you only ever pay on money that actually settled. invoice.updated fires a lot and includes drafts, so it's the wrong trigger for a payout ledger.

async function handleInvoicePaid(invoice) {
  // Only invoices you actually collected on.
  if (invoice.amount_paid <= 0) return;

  const referral = await lookupReferralByCustomer(invoice.customer);
  if (!referral) return;

  const { amount, currency } = commissionableAmount(invoice);
  if (amount <= 0) return; // net-zero or credit-only invoice

  const rate = referral.rate; // e.g. 0.30
  const commission = Math.round(amount * rate);

  await recordCommission({
    // Idempotency: invoice.id is stable across webhook retries.
    idempotencyKey: `commission:${invoice.id}`,
    affiliateId: referral.affiliateId,
    invoiceId: invoice.id,
    currency,
    amount: commission,
    withinWindow: monthsSince(referral.startedAt) < 12, // 30% for 12 months
  });
}

Stripe retries webhooks. If your recordCommission isn't keyed on something stable like invoice.id, a retry double-pays the affiliate. Make the insert a unique constraint on the key and swallow the duplicate.

Clawbacks: refunds and credit notes

A commission you booked on Monday can evaporate on Friday when the customer disputes the charge or you issue a credit note. If you already paid the affiliate on that revenue, you're now out of pocket.

Listen for credit_note.created. A credit note reduces what the customer owes or refunds them, and it carries its own amount and line items.

async function handleCreditNote(creditNote) {
  const referral = await lookupReferralByCustomer(creditNote.customer);
  if (!referral) return;

  // creditNote.amount is positive; it represents money removed from the sale.
  const clawbackBase = creditNote.amount; // smallest currency unit
  const clawback = Math.round(clawbackBase * referral.rate);

  await recordCommission({
    idempotencyKey: `clawback:${creditNote.id}`,
    affiliateId: referral.affiliateId,
    invoiceId: creditNote.invoice,
    currency: creditNote.currency,
    amount: -clawback, // negative entry against the ledger
  });
}

Book it as a negative ledger entry rather than deleting the original row. You want an audit trail showing $12.60 earned and $12.60 reversed, not a silent disappearance. When the affiliate asks why their balance dropped, the answer should be in the ledger.

For straight refunds without a credit note, handle charge.refunded the same way, using charge.amount_refunded as the base.

Gotchas worth writing down

Negative proration lines are a feature, not noise. Don't filter them out with if (line.amount > 0). That's exactly the bug that overpays on downgrades.
Pay on net revenue you keep. Sum line amounts (pre-tax subtotal), not total, unless you genuinely intend to pay commission on sales tax and Stripe fees. Most programs don't.
Idempotency on every write. Webhooks retry, and invoice.paid can fire more than once in edge cases. Key every ledger entry on a stable Stripe object id.
One currency per ledger entry. Store the currency next to the amount and refuse to add across currencies.
A net-zero proration invoice pays zero. When someone downgrades and their proration nets negative, amount_paid is 0 and there's nothing to commission. Your amount <= 0 guard handles it.

Get the line-item math right once and upgrades, downgrades, and mid-cycle seat changes all fall out of the same code path. The affiliate earns on what you actually banked, and your clawback ledger stays honest when the money moves back.

I build Referralful, affiliate software for SaaS built on Stripe, so this proration edge case is one I've had to get exactly right.

Affiliate commission clawbacks: only pay on money you actually keep

Mihir kanzariya — Thu, 23 Jul 2026 02:11:30 +0000

The naive version of affiliate payout logic pays the affiliate the moment a customer's first invoice clears. It works right up until that customer refunds a few days later, and you've already booked (or in the worst case, sent) a commission on revenue that walked back out the door. Now you're down the sale and the payout.

If you run any affiliate or referral program on Stripe, this is the trap: invoice.paid fires, you cut the commission, and then a refund, a chargeback, or a same-week cancel undoes the money underneath it. The fix is to treat a commission as something that has to vest before it's real.

Commissions have a lifecycle, not a boolean

A commission is not "paid / not paid." It moves through states:

pending  -> approved -> paid
   |
   +-> reversed   (refund, dispute, or early cancel before it vested)

pending means the invoice cleared but the money isn't safe yet. approved means the hold window passed and no refund landed, so it's payable. paid means you actually sent it. reversed (or voided) means the underlying charge came back before the commission vested.

Here's the row I store per commission:

// commissions table
{
  id:           "cm_123",
  affiliate_id: "aff_42",
  invoice_id:   "in_1P...",     // the Stripe invoice this came from
  charge_id:    "ch_1P...",     // the charge, for refund/dispute matching
  amount:       1500,           // commission in cents
  base_amount:  5000,           // the invoice amount we based it on
  status:       "pending",      // pending | approved | paid | reversed
  hold_until:   "2026-08-21",   // when it's eligible to approve
  created_at:   "2026-07-22"
}

Storing both invoice_id and charge_id matters. Refunds and disputes arrive as charge events, cancellations arrive as subscription events, and you need to trace either one back to the exact commission row.

The webhook handler

Four events do the work. invoice.paid opens a pending commission. charge.refunded and charge.dispute.created reverse one. customer.subscription.deleted stops future commissions but leaves vested ones alone.

Dedupe on event.id first. Stripe retries webhooks, and without idempotency a single refund can reverse the same commission twice.

app.post("/webhooks/stripe", async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body, req.headers["stripe-signature"], process.env.WH_SECRET
  );

  // idempotency: bail if we've seen this event id before
  const fresh = await db.recordEventOnce(event.id);
  if (!fresh) return res.json({ received: true, duplicate: true });

  switch (event.type) {
    case "invoice.paid":
      await onInvoicePaid(event.data.object);
      break;
    case "charge.refunded":
      await onChargeRefunded(event.data.object);
      break;
    case "charge.dispute.created":
      await onDispute(event.data.object);
      break;
    case "customer.subscription.deleted":
      await onSubscriptionCanceled(event.data.object);
      break;
  }
  res.json({ received: true });
});

recordEventOnce is a single insert into a processed_events(event_id primary key) table that returns false on conflict. Cheap and reliable.

Opening a pending commission with a hold window

On invoice.paid, resolve which affiliate referred the customer (I stash affiliate_id in the Stripe customer's metadata at signup), compute the cut, and set hold_until. I use 60 days because it sits past Stripe's common refund and most dispute windows. Pick a number that matches your own refund policy.

async function onInvoicePaid(invoice) {
  const affiliateId = await resolveAffiliate(invoice.customer);
  if (!affiliateId) return; // not a referred customer

  const rate = 0.30;
  const holdDays = 60;
  const holdUntil = new Date(Date.now() + holdDays * 864e5);

  await db.commissions.insert({
    affiliate_id: affiliateId,
    invoice_id:   invoice.id,
    charge_id:    invoice.charge,          // charge on this invoice
    base_amount:  invoice.amount_paid,
    amount:       Math.round(invoice.amount_paid * rate),
    status:       "pending",
    hold_until:   holdUntil
  });
}

The worker that vests commissions

A daily cron promotes pending rows to approved once hold_until has passed. The condition is simple: the hold is up and the row is still pending (a refund would have already flipped it to reversed).

async function vestCommissions() {
  const due = await db.commissions.find({
    status: "pending",
    hold_until: { $lte: new Date() }
  });
  for (const c of due) {
    await db.commissions.update(c.id, { status: "approved" });
  }
}
// run daily

Approved rows are what your payout run reads from. Nothing gets paid until it clears this gate.

Reversing correctly, including partial refunds

When charge.refunded fires, match on charge_id and prorate. A charge object carries amount and amount_refunded, so a partial refund only claws back the matching fraction of the commission.

async function onChargeRefunded(charge) {
  const c = await db.commissions.findOne({ charge_id: charge.id });
  if (!c) return;

  const refundRatio = charge.amount_refunded / charge.amount;
  const clawback = Math.round(c.amount * refundRatio);

  if (charge.refunded) {
    // fully refunded
    await db.commissions.update(c.id, { status: "reversed" });
  } else {
    // partial: shrink the commission, keep it in its current state
    await db.commissions.update(c.id, {
      amount: c.amount - clawback,
      base_amount: charge.amount - charge.amount_refunded
    });
  }

  if (c.status === "paid") await recordDebt(c.affiliate_id, clawback);
}

If the commission was still pending or approved, reversing it costs you nothing (you never sent it). If it was already paid, recordDebt books a negative balance you net against the affiliate's next payout. charge.dispute.created runs the same reversal, usually reversing the full amount since disputes pull the whole charge.

The recurring gotcha

If you pay recurring commissions (say 30% for 12 months), every invoice.paid is its own commission row with its own hold_until. That has two consequences people miss.

A customer.subscription.deleted should stop future commissions, not reach back and reverse past ones that already vested. Month 1 through month 5 were real money you kept, so the affiliate keeps them. Cancel only kills months 6 onward.

async function onSubscriptionCanceled(subscription) {
  // future invoices simply stop firing invoice.paid, so there's
  // nothing to reverse. only void commissions still inside their
  // hold window, since that money may still refund.
  await db.commissions.updateMany(
    { subscription_id: subscription.id, status: "pending",
      hold_until: { $gt: new Date() } },
    { status: "reversed" }
  );
}

The mental model: a churn stops the faucet, a refund drains a specific bucket. Don't conflate them.

This is the kind of logic I spend a lot of time on building Referralful. Getting the hold window and the refund matching right is what keeps you from paying out on revenue you didn't keep. Store the charge id on every commission, put a hold between "invoice cleared" and "payable," and treat each recurring invoice as its own vesting clock. Do that and a day-4 refund costs you the sale, but never the payout on top of it.

Tying a Stripe subscription back to the affiliate who referred it

Mihir kanzariya — Wed, 22 Jul 2026 02:44:28 +0000

Every affiliate program has the same first hard problem: when a payment succeeds, which affiliate gets the credit? The tracking link and the Stripe payment are two different worlds, and nothing connects them unless you deliberately carry the attribution through. Here is how to thread it end to end on Stripe.

The chain you have to preserve

A referred signup passes through several Stripe objects, and the affiliate id has to survive every hop:

click (cookie) -> Checkout Session -> Subscription -> Invoice -> Charge

Drop the id anywhere in that chain and the webhook that finally tells you money moved has no idea who to pay.

Start at Checkout

When you create the Checkout Session, stamp the affiliate id on it. Two fields matter:

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: PRICE_ID, quantity: 1 }],
  // handy, but lives only on the session
  client_reference_id: affiliateId,
  // propagates onto the Subscription you are about to create
  subscription_data: {
    metadata: { affiliate_id: affiliateId },
  },
  success_url: '...',
  cancel_url: '...',
});

client_reference_id is convenient but it stays on the Session. The important one is subscription_data.metadata, because that copies the affiliate id onto the Subscription itself, which is the object every future renewal traces back to.

Read it off the invoice, not the session

For a subscription you do NOT want to grant commission on checkout.session.completed. That fires once, at signup, so you would miss every renewal. Listen to invoice.paid instead, which fires for the first payment AND every recurring one:

// webhook: invoice.paid
const invoice = event.data.object;

// pull the subscription to read the metadata you stamped at checkout
const subscription = await stripe.subscriptions.retrieve(invoice.subscription);
const affiliateId = subscription.metadata.affiliate_id;
if (!affiliateId) return; // not a referred customer

await recordCommission({
  affiliate_id: affiliateId,
  invoice_id: invoice.id,
  amount_cents: Math.round(invoice.amount_paid * COMMISSION_RATE),
  // first invoice or a renewal? billing_reason tells you
  kind: invoice.billing_reason, // 'subscription_create' vs 'subscription_cycle'
});

billing_reason is what lets you enforce rules like commission for the first 12 months only, or first-payment bounties, without guessing.

The cookie-to-checkout gap

The one part Stripe cannot help with is getting the affiliate id onto the Checkout Session in the first place. That is on you: read the affiliate cookie on your server when the user clicks subscribe, and pass it into the session create call. Rely on a client-side value and an adblocker or a cleared cookie silently drops the attribution, so the affiliate never gets paid for a sale they earned.

Why metadata beats your own lookup table

You could keep a table mapping customer to affiliate. But subscriptions get their billing anchor changed, customers get merged, test data leaks into prod. Stamping the id directly on the Stripe object means the source of truth travels with the object. When you are debugging a missing commission six months later, subscription.metadata.affiliate_id is a five-second answer instead of a join across three tables.

(I work on Referralful, which does this attribution automatically on top of Stripe. The mechanics above are the same whether you build it or buy it.)

Clawing back affiliate commissions when a Stripe payment is refunded or disputed

Mihir kanzariya — Tue, 21 Jul 2026 02:41:11 +0000

Affiliate programs are easy on the happy path. Someone clicks a link, subscribes, you owe a commission. The part that quietly loses you money is what happens next: the customer refunds in week two, or files a dispute in month two, and you already paid the affiliate for a sale that no longer exists.

Here is how to handle the reversal cleanly on Stripe.

The two events you actually care about

Stripe fires a webhook for both cases:

charge.refunded when you refund all or part of a payment.
charge.dispute.created when the cardholder files a chargeback.

Both mean the revenue you attributed to an affiliate is gone, fully or partially, so the commission tied to it has to be reversed.

Match the reversal back to the commission

The trick is being able to go from a Stripe charge back to the commission you recorded. Store that link at the moment you create the commission, keyed on the charge or invoice id:

// when you record a commission on a successful payment
await db.commissions.insert({
  affiliate_id: affiliateId,
  stripe_charge_id: charge.id,
  stripe_invoice_id: invoice.id,
  amount_cents: Math.round(charge.amount * commissionRate),
  status: 'pending', // not yet paid out
});

Now the refund handler can find the exact row:

// webhook: charge.refunded
const charge = event.data.object;

const commission = await db.commissions.findOne({
  stripe_charge_id: charge.id,
});
if (!commission) return; // not an affiliate sale, ignore

// partial refunds are common, so reverse proportionally
const refundedRatio = charge.amount_refunded / charge.amount;
const clawback = Math.round(commission.amount_cents * refundedRatio);

if (commission.status === 'pending') {
  // not paid yet: just reduce or void it
  await db.commissions.update(commission.id, {
    amount_cents: commission.amount_cents - clawback,
    status: refundedRatio === 1 ? 'voided' : 'pending',
  });
} else {
  // already paid: carry a negative adjustment into the next payout
  await db.commissions.insert({
    affiliate_id: commission.affiliate_id,
    stripe_charge_id: charge.id,
    amount_cents: -clawback,
    status: 'adjustment',
  });
}

The branch that matters is pending vs already-paid. If you have not paid the affiliate yet, you can shrink or void the commission. If you already paid it, you cannot un-send the money, so you carry a negative adjustment into their next payout.

Disputes need a different default

A charge.dispute.created is not final the way a refund is. You might win it. So do not void the commission on the dispute event, freeze it:

// webhook: charge.dispute.created
await db.commissions.update(
  { stripe_charge_id: event.data.object.charge },
  { status: 'held' } // exclude from payouts until resolved
);

Then act on charge.dispute.closed and read event.data.object.status: if it is lost, reverse it like a refund; if won, move it back to pending.

Make the handler idempotent

Stripe retries webhooks, and it will happily deliver the same charge.refunded twice. If your clawback is not idempotent you will double-reverse and underpay the affiliate. Guard on the event id before you touch a commission:

const seen = await db.processed_events.findOne({ id: event.id });
if (seen) return; // already handled
await db.processed_events.insert({ id: event.id });

Why this matters more than it looks

Skip the reversal and your affiliate payouts slowly drift above your actual revenue. Refund rates of 5 to 10% are normal for SaaS, so a program paying 30% quietly overpays a few percent of revenue every month, and you only catch it when you reconcile by hand.

Getting the refund and dispute path right from day one is the difference between an affiliate program that pays for itself and one that leaks.

(For context, I work on Referralful, which handles this reconciliation automatically on top of Stripe. The logic above is the same whether you build it or buy it.)

Reconciling your affiliate payouts against Stripe (the audit nobody builds)

Mihir kanzariya — Mon, 20 Jul 2026 07:15:27 +0000

Your app has a ledger that says "we owe affiliates $4,210 this month." Stripe has its own record of what was actually charged, refunded, and settled. Everyone assumes those two numbers agree. They drift, quietly, and you find out when an affiliate emails asking why their payout is short.

The drift comes from ordinary things: a webhook that never arrived, a refund that updated Stripe but not your ledger, a currency rounding, a duplicate credit from a retried event. None of these are exotic. Any one of them means your ledger is now telling a story Stripe cannot back up.

The fix is a reconciliation job: once a period, diff your ledger against Stripe as the source of truth and flag every mismatch before you pay anyone.

The core idea

Stripe is the source of truth for money. Your ledger is a derived view. A derived view has to be provable against its source, so you check both directions.

Direction 1: every ledger credit maps to a real paid invoice

Pull the paid invoices for the period, then confirm each commission you recorded points at one that actually settled.

// paid invoices in the window, expanded to see discounts/amounts
const invoices = [];
for await (const inv of stripe.invoices.list({
  status: 'paid',
  created: { gte: periodStart, lt: periodEnd },
  limit: 100,
})) {
  invoices.push(inv);
}
const paidById = new Map(invoices.map(i => [i.id, i]));

for (const credit of ledger.creditsForPeriod(periodStart, periodEnd)) {
  const inv = paidById.get(credit.invoice_id);
  if (!inv) {
    flag('credit_without_paid_invoice', credit); // paid on something Stripe has no record of
  } else if (credit.base_amount !== inv.amount_paid) {
    flag('base_mismatch', { credit, expected: inv.amount_paid });
  }
}

credit_without_paid_invoice is the dangerous one. It means you are about to pay real money against a charge that never truly settled.

Direction 2: every affiliate-tagged paid invoice has a credit

This catches the missed webhooks, the silent under-payments that make affiliates quit.

for (const inv of invoices) {
  const affiliateId = inv.customer_metadata?.affiliate_id;
  if (!affiliateId) continue;
  if (!ledger.hasCreditForInvoice(inv.id)) {
    flag('missing_credit', { invoice: inv.id, affiliate_id: affiliateId });
  }
}

A pile of missing_credit flags usually means your webhook handler was down for a stretch, or an event type you do not listen to (like an out-of-band paid invoice) slipped through.

Direction 3: refunds became clawbacks

A refund lives in Stripe. If it never propagated to your ledger, you are paying commission on money you gave back.

for await (const refund of stripe.refunds.list({ created: { gte: periodStart, lt: periodEnd }, limit: 100 })) {
  const invoiceId = await invoiceForCharge(refund.charge);
  if (invoiceId && ledger.hasCreditForInvoice(invoiceId) && !ledger.hasClawbackForRefund(refund.id)) {
    flag('refund_without_clawback', { refund: refund.id, invoice: invoiceId });
  }
}

What to do with the flags

Do not auto-correct silently. Reconciliation should produce a short report a human signs off on before payout runs:

credit_without_paid_invoice and refund_without_clawback -> hold those amounts, they overpay.
missing_credit -> backfill, then figure out which webhook you dropped so it stops recurring.
base_mismatch -> almost always a coupon or proration you computed off the wrong number.

The goal is not zero mismatches forever. It is that on payout day you can say, with a report to back it, that every dollar leaving matches a dollar Stripe actually collected and kept. That is the difference between an affiliate program you can scale and one that becomes a monthly argument.

We run this reconciliation inside Referralful (affiliate software on Stripe, which I help build) so payouts are provable against Stripe rather than trusted. If you build your own, the one habit worth stealing: never pay from your ledger alone, pay from your ledger after it has been proven against Stripe.

Coupons and affiliate commissions on Stripe: what do you actually pay?

Mihir kanzariya — Sun, 19 Jul 2026 04:17:07 +0000

Here is a case that quietly breaks a lot of affiliate programs: a customer uses a discount code and came through an affiliate link. Your $50/month plan gets a 40% coupon, they pay $30, and your affiliate earns 30%. Do you pay the affiliate 30% of $50 or 30% of $30? Get this wrong in the generous direction and a discounted sale can pay out more in commission than it brought in.

There are two separate questions hiding here, and Stripe gives you a clean answer to both.

Pay on what Stripe actually charged, not the sticker price

The single rule that keeps you solvent: commission is a percentage of amount_paid, which already has the discount subtracted. Never compute off the plan's list price.

// on invoice.paid
const charged = invoice.amount_paid; // already net of any coupon, in cents
const commission = Math.round(charged * 0.30);

Why it matters: say you pay 30% on the sticker $50 ($15) for a sale where the customer only paid $30 after a coupon. Your gross on that sale is $30, you hand $15 to the affiliate, and after Stripe fees you are close to breaking even on a customer you are supposed to be profiting from. Do that across a launch-week coupon and the program bleeds. Paying on amount_paid ($9 here) keeps the math sane.

When the coupon IS the attribution

A lot of programs skip links entirely and give each affiliate a unique code: JANE20. The code does double duty, it discounts the customer and it tells you who to credit. You read it straight off the invoice.

// invoice.paid, attribute via the promotion code used
const lines = invoice.lines?.data ?? [];
const discount = invoice.discount || lines[0]?.discount;
const promoCode = discount?.promotion_code; // e.g. "promo_123"

if (promoCode) {
  const affiliateId = await affiliateForPromoCode(promoCode); // your mapping
  if (affiliateId) {
    await ledger.credit({
      affiliate_id: affiliateId,
      amount: Math.round(invoice.amount_paid * 0.30),
      idempotency_key: invoice.id,
    });
  }
}

Map each Stripe promotion code to an affiliate when you create it, so this lookup is a single row read, not a guess.

The stacking trap: do not double-attribute

The mess happens when both signals fire: the customer clicked an affiliate link (cookie says affiliate A) and also entered a general storewide coupon that happens to map to nobody, or worse, to affiliate B. Now two systems each think they own the sale.

Pick one source of truth and write it down as a rule:

If a code maps to a specific affiliate, the code wins (it is explicit intent).
Otherwise fall back to the click attribution stored at signup.
Never let both credit the same invoice. Key every credit to invoice.id so even a double-fire can only ever write one row.

const affiliateId =
  (await affiliateForPromoCode(promoCode)) ||   // explicit code first
  invoice.customer_metadata?.affiliate_id;      // then click attribution

One more: does the affiliate keep earning after the coupon expires?

Intro coupons end. The customer paid $30 for three months, then rolls to full $50. Because you are always paying a percentage of amount_paid, this just works: the commission rises to 30% of $50 on its own when the real charge goes up. No special case, as long as you never hardcoded the discounted number.

The whole thing reduces to one habit: treat amount_paid as the only number that decides commission, and treat the promotion code as an attribution signal, not a reason to change the math. We handle both in Referralful (affiliate software on Stripe, which I help build) so coupon stacking does not turn into an overpayment, but the rules above are the same whether you buy or build.

Your 60-day affiliate cookie is lying on Safari. Here is how to fix attribution.

Mihir kanzariya — Sat, 18 Jul 2026 04:04:30 +0000

Almost every affiliate tool advertises a cookie window: 30 days, 60 days, 90. The implication is that if someone clicks an affiliate link today and buys seven weeks later, the affiliate still gets credit. On Chrome, mostly true. On Safari, that number is fiction.

Safari's Intelligent Tracking Prevention caps client-side, script-set cookies at 7 days, and in some cases 24 hours. So if you set your affiliate cookie with JavaScript, a huge slice of your traffic loses its attribution a week after the click, silently. Firefox and Brave block a lot of third-party tracking outright. Your 60-day promise quietly becomes a 7-day promise for anyone on the privacy-forward half of the internet.

The fix is to stop trusting the cookie to carry attribution for 60 days. Use it only to bridge one gap: from the click to the signup. After that, attribution lives in your database, where no browser can expire it.

Capture the referral the moment they land

On the landing hit, read the ref and store it. Set a first-party cookie (from your own domain, server-side where you can), but treat it as short-lived glue, not the source of truth.

// GET /?ref=aff_123  (your own server, first-party)
app.get('/', (req, res) => {
  const ref = req.query.ref;
  if (ref) {
    res.cookie('aff_ref', ref, {
      maxAge: 30 * 24 * 60 * 60 * 1000, // best effort; Safari may shorten it
      httpOnly: false,
      sameSite: 'lax',
    });
    // also stash it against the anonymous session server-side
    req.session.aff_ref = req.session.aff_ref || ref;
  }
  res.render('landing');
});

Notice the cookie is first-party (your domain), not a third-party tracker. That already survives far better than a script injected from an affiliate vendor's domain. But you still do not rely on it lasting 60 days.

Move attribution to your database at signup

The instant someone creates an account, promote the referral from the fragile cookie/session into a durable record. This is the step that actually makes the window real.

async function onSignup(user, req) {
  const ref = req.session.aff_ref || req.cookies.aff_ref;
  if (ref) {
    await db.users.update(user.id, {
      affiliate_id: ref,
      attributed_at: new Date(), // the window starts HERE, server-side
    });
    // and onto the Stripe customer, so billing events carry it forever
    await stripe.customers.update(user.stripe_customer_id, {
      metadata: { affiliate_id: ref },
    });
  }
}

Now the affiliate link only has to survive from click to signup, which is usually minutes to days, well inside even Safari's 24-hour floor for the tightest cases. The 60-day window is measured from attributed_at in your own database, not from a cookie the browser is free to delete.

Measure the window where it cannot be tampered with

When a payment comes in, you check the window against your stored timestamp, not against whether a cookie still exists.

// on invoice.paid
const affiliateId = invoice.customer_metadata?.affiliate_id;
const attributedAt = await db.attribution.getTimestamp(invoice.customer);
if (affiliateId && withinDays(attributedAt, 60)) {
  await ledger.credit({ affiliate_id: affiliateId, amount: commissionOn(invoice.amount_paid) });
}

The mental shift is the whole thing: the cookie is a bridge, not a vault. It carries attribution across a single gap and then hands it to your database, which honors the full window regardless of browser. Anyone still leaning on a 60-day JavaScript cookie is under-crediting their Safari affiliates and does not know it.

We handle this in Referralful (affiliate software on Stripe, which I help build), so the 60-day cookie our marketing page mentions is actually a 60-day server-side window, not a client-side hope. If you roll your own, the one rule to keep: never let a browser be the thing that remembers who referred a paying customer.

Paying your affiliates with Stripe Connect (the payout side nobody documents)

Mihir kanzariya — Fri, 17 Jul 2026 03:53:27 +0000

Most affiliate-tracking tutorials stop at "calculate the commission." Then you are sitting on a table of amounts you owe 40 people and no clean way to actually send the money. Manual PayPal and bank transfers work for three affiliates and fall apart at thirty, and now you also own their tax forms and KYC.

Stripe Connect handles that side. Your affiliates onboard once, Stripe verifies them and collects tax info, and you move money to them with an API call. Here is the shape of it.

One connected account per affiliate

Create an Express account when an affiliate joins. Express means Stripe hosts the onboarding and dashboard, so you never touch their bank details.

const account = await stripe.accounts.create({
  type: 'express',
  email: affiliate.email,
  capabilities: { transfers: { requested: true } },
  metadata: { affiliate_id: affiliate.id },
});

// store account.id against your affiliate record

Then send them through onboarding with a one-time link:

const link = await stripe.accountLinks.create({
  account: account.id,
  refresh_url: 'https://yourapp.com/affiliate/reauth',
  return_url: 'https://yourapp.com/affiliate/done',
  type: 'account_onboarding',
});
// redirect the affiliate to link.url

Only pay accounts that are actually ready

Do not assume onboarding finished because they clicked through. Check the account before every payout. An affiliate who abandoned KYC will fail the transfer and leave you reconciling a mess.

const acct = await stripe.accounts.retrieve(affiliate.stripe_account_id);
if (!acct.payouts_enabled) {
  // nudge them to finish onboarding, skip this run
  return;
}

Move the money

Once commission clears its hold and the account is ready, create a transfer from your platform balance to the affiliate:

await stripe.transfers.create({
  amount: commissionCents,          // what you owe, in cents
  currency: 'usd',
  destination: affiliate.stripe_account_id,
  transfer_group: `payout_${payoutRun.id}`,
  metadata: { affiliate_id: affiliate.id, run: payoutRun.id },
}, { idempotencyKey: `transfer_${affiliate.id}_${payoutRun.id}` });

The idempotencyKey matters. Payout jobs get retried, and without it a timeout that actually succeeded server-side turns into a double payment. Key it to the affiliate plus the run, not the wall clock.

The gotchas that bite in production

Fund the platform balance. Transfers pull from your Stripe balance. If it is empty because payouts to your own bank already swept it, the transfer fails. Keep a buffer or use a separate payout schedule.
Hold past the refund window. Do not transfer commission on an invoice that can still be refunded. Pay on a delay (for example, monthly for the prior month) so a refund reverses a ledger row instead of clawing back real money already sent.
Batch, but track per affiliate. One transfer_group per run, one idempotency key per affiliate, so a partial failure is easy to retry without touching the affiliates who already got paid.
Currency. Transfers settle in the destination account's currency. If you charged in EUR and pay in USD, decide where the conversion happens and be consistent, or your ledger will not reconcile.

The calculation side is where the logic lives, but the payout side is where the money actually leaves, and it is the part that generates angry emails when it is wrong. Connect turns "I owe 40 people money" into one idempotent job.

We built this into Referralful (affiliate software on Stripe, which I help build) so the onboarding, holds, and transfers run without anyone touching a spreadsheet. Even rolling your own, Express accounts plus idempotent transfers are the two pieces to get right first.

Catching affiliate self-referrals before you pay out (Stripe)

Mihir kanzariya — Thu, 16 Jul 2026 03:53:01 +0000

Once your affiliate program pays real money, someone will refer themselves. They sign up through their own link, or route a friend they coach through it, collect the commission, and on a recurring product they can churn right after the first payout. If you credit commission the moment an invoice is paid, you just funded a discount to yourself.

The good news: Stripe already hands you most of the signals to catch this. You do not need a fraud vendor to start, you need to look at the data you are storing anyway.

The strongest signal: payment method fingerprint

Every card in Stripe has a fingerprint that stays stable across customers. If the affiliate's own subscription and the customer they referred were paid with the same physical card, that is not a coincidence.

async function sharesPaymentMethod(affiliateCustomerId, referredCustomerId) {
  const [a, b] = await Promise.all([
    stripe.paymentMethods.list({ customer: affiliateCustomerId, type: 'card', limit: 20 }),
    stripe.paymentMethods.list({ customer: referredCustomerId, type: 'card', limit: 20 }),
  ]);
  const aPrints = new Set(a.data.map(pm => pm.card.fingerprint));
  return b.data.some(pm => aPrints.has(pm.card.fingerprint));
}

A match here is close to a smoking gun. Flag it, do not pay it.

Cheaper signals worth stacking

Fingerprint is the best one, but a few more catch the sloppier cases:

Email overlap. Same address, obvious plus-addressing (me+ref@), or the same domain on a personal-email product. Normalize before comparing.
Billing address match between the two customers.
Radar / IP. If you use Stripe Radar, the charge carries risk signals and an IP. Same IP for referrer and referred is worth a flag.
Churn inside the window. The referred subscription cancels or refunds right after the commission-eligible invoice. This is the classic grab-and-run.

None of these alone should auto-ban. Stacked, they sort the obvious abuse from the false positives.

Where to run the check

Do it at commission time, not signup. On invoice.paid, before you write the credit:

// case 'invoice.paid'
const affiliateId = invoice.customer_metadata?.affiliate_id;
if (affiliateId) {
  const affiliateCustomer = await lookupAffiliateCustomer(affiliateId);
  const selfReferral =
    affiliateCustomer &&
    await sharesPaymentMethod(affiliateCustomer.stripe_id, invoice.customer);

  if (selfReferral) {
    await ledger.flagForReview({ affiliate_id: affiliateId, invoice: invoice.id, reason: 'card_fingerprint_match' });
  } else {
    await ledger.credit({ affiliate_id: affiliateId, amount: commissionOn(invoice.amount_paid), idempotency_key: invoice.id });
  }
}

The pragmatic policy that stops most of the loss: hold the commission until the referred subscription clears its refund window, and route fingerprint matches to a human instead of a payout. You lose nothing legitimate by waiting a few weeks, and you stop paying people to refer themselves.

We handle this inside Referralful (affiliate software built on Stripe, which I help build), so the fingerprint and churn checks run before a payout is ever approved. Even if you build your own, the payment method fingerprint is the single highest-value check to add first.