How we built Stripe Credits: A programmable, auditable way to pay your Stripe fees

Summary

Stripe Fee Credits replaces ad-hoc discounts and manual cash adjustments with a programmable, auditable virtual balance dedicated to eligible Stripe fees. The architecture has three layers: a standalone gRPC credits engine for metadata, policies, lifecycle, and audit history; logical financial accounts built on Money Movement and Storage; and fee-settlement orchestration that applies eligible credits before the primary balance. Logical accounts carry ledger balances without representing real cash, while platform checks restrict Originated Money Transfers to logical-to-logical movements and exclude these accounts from cash sweeps. Prepaid and Stripe-funded credits share the user experience but use separate funds flows: prepayments create deferred revenue and collect tax at drawdown, whereas Stripe-funded credits are booked as Stripe costs with taxes written off. The resulting infrastructure supports incentives, prepaid annual fees, and other programs across 26+ countries, with Dashboard balances and real-time auditability, while avoiding bespoke engineering for each commercial model.

Takeaways

1. 1

   Logical financial accounts store virtual balances in Stripe’s internal ledger without backing them with bank accounts or treating them as withdrawable user funds.

2. 2

   Prepaid credits create deferred revenue at funding and collect tax at drawdown; Stripe-funded credits are recorded as a Stripe cost and their taxes are written off.

3. 3

   The shared credit infrastructure supports sales incentives, prepaid annual fee agreements, acquisition credits, onboarding credits, and courtesy credits without bespoke engineering for each program.