Stripe Referral Integration: Gate Rewards on Payment

A Stripe referral integration done right gates the reward on invoice.paid, not on signup. A referred user can sign up, poke around, and churn before ever being billed. Firing it at signup pays for traffic, not revenue. Gating on payment, then holding the payout through Stripe's refund window, is the fix.

Why a Stripe referral integration should gate rewards on invoice.paid

Gating referral rewards on Stripe's invoice.paid event means a reward fires only after cash actually lands, not when a form submits. Signup-triggered rewards pay for free trials, fake accounts, and people who bounce in week one. invoice.paid confirms a card was charged and Stripe settled the payment. That's the first real revenue signal.

For subscription SaaS this matters doubly. A monthly plan generates a new invoice every billing cycle, so the signup event and the first real payment can sit weeks apart, especially behind a free trial. A referral reward tied to payment confirmation keeps incentive spend aligned with recognized revenue, not vanity signups. ReferralFlo's Growth Graph attribution ties the original referral link to the Stripe customer object at click-through, so when invoice.paid eventually fires, the reward still resolves to the correct referrer instead of getting lost between signup and billing.

Which Stripe webhook events drive the reward state machine

Three Stripe webhook events drive the lifecycle: invoice.paid marks the reward pending, charge.refunded or invoice.payment_failed triggers a clawback review, and charge.dispute.created pauses payout until resolution. ReferralFlo's webhook listener consumes these events, maps the Stripe customer ID back to the referral record, and writes each state transition to the reward escrow's immutable audit log.

Stripe's own webhook documentation covers signature verification and retry behavior, both of which matter here: a dropped webhook should never leave a reward stuck in limbo. ReferralFlo connects to Stripe as one of its named integrations, alongside Shopify and HubSpot, so this listener runs without custom infrastructure. Full event payload schemas live in ReferralFlo's docs for teams wiring the SDK directly.

How long to hold the reward in escrow before paying out

ReferralFlo's reward escrow can hold a referral payout pending conditions, such as a refund window closing, instead of releasing it the moment invoice.paid fires. A common pattern sets the hold equal to the product's refund policy period: a 14-day refund window means a 14-day escrow hold, after which eligible rewards release automatically with no manual approval step.

Take an illustrative $49/month SaaS plan with a 14-day refund policy, a $25 referrer reward, and a $10 referred-customer credit. invoice.paid fires on day 0, moving both rewards to held. If charge.refunded hasn't landed by day 15, ReferralFlo's escrow logic releases both rewards automatically. Setting an escrow window at all mirrors a broader pattern in consumer payments: the CFPB's Regulation E gives card issuers up to 45 days to resolve a disputed electronic transaction, a useful anchor when a team is deciding how long is long enough. This hold configuration lives inside referral management, where approvals, escrow duration, and the audit log are set per program. Use the reward calculator to size a double-sided reward against margin before locking in the hold period.

How a referral refund clawback works when Stripe issues a refund

When charge.refunded arrives after a reward has already been released, the fix isn't deleting history, it's reversing it. ReferralFlo logs a clawback transaction against the immutable audit log, reverses store credit or disables an unredeemed gift card, and flags cash payouts already sent via bank transfer for manual recovery or offset against a future reward.

Partial refunds complicate the math but don't change the mechanism. If Stripe refunds half an invoice, ReferralFlo can recalculate the reward pro rata against the net amount actually collected, instead of clawing back the full payout for a partial adjustment. Stripe's refund documentation notes that partial refunds keep the original charge object active, which is what makes a pro-rata recalculation possible instead of an all-or-nothing reversal. That rule belongs in the program's written reward policy. It shouldn't get decided per ticket.

Avoiding false clawbacks: disputes, chargebacks, and failed renewals

A chargeback is not the same signal as a voluntary refund, and treating them identically creates false clawbacks. charge.dispute.created should pause a reward instead of reversing it immediately, since disputes can resolve in the merchant's favor. Only a final charge.refunded event, or a lost dispute, should trigger the permanent reversal ReferralFlo writes to the referral record.

invoice.payment_failed deserves the same caution in reverse: a failed renewal charge in month two shouldn't claw back a reward already earned on month one's successful payment. The clawback logic should key off the specific invoice tied to the reward, not the customer's overall billing status. The same discipline that catches self-referrals and IP collisions in a practical anti-fraud checklist applies here: automate the obvious cases, and route the ambiguous ones to manual review instead of an automatic reversal.