Designing Payment and Billing Systems
1. Designing Payment Gateway Integration
| Element | Detail |
|---|---|
| Providers | Stripe, Adyen, Braintree, Checkout.com |
| Hosted fields / Elements | Avoid touching card data (PCI scope) |
| 3DS / SCA | EU mandatory |
| Idempotency-Key | Required header |
| Webhook for results | Async outcome |
2. Designing Subscription Management
| Element | Detail |
|---|---|
| Plan / price catalog | Tiered pricing |
| Lifecycle | trial → active → past_due → canceled |
| Proration | Mid-cycle upgrades |
| Trial | Free or paid trial |
| Pause / cancel | Self-serve |
3. Designing Recurring Billing
| Aspect | Detail |
|---|---|
| Cycle | Monthly / annual / custom |
| Anchor date | Subscription start determines cycle |
| Dunning | Retry failed payments on schedule |
| Smart retries | Provider intelligence (Stripe) |
| Card update notifications | Account Updater service |
4. Designing Invoice Generation
| Element | Detail |
|---|---|
| Numbering | Monotonic, gap-free per jurisdiction |
| Line items | Plan + usage + adjustments |
| Tax | Avalara, Stripe Tax, TaxJar |
| Generated; stored in object store | |
| Localization | Currency, language |
5. Designing Payment Retry Strategy
| Strategy | Detail |
|---|---|
| Schedule | Day 1, 3, 5, 7 |
| Smart retry | Skip if soft decline expected to recur |
| Email reminders | Update payment method link |
| Grace period | Service active during dunning |
| Hard decline | Cancel subscription |
6. Designing Payment Webhook Handling
| Practice | Detail |
|---|---|
| Verify signature | Stripe-Signature etc. |
| Return 2xx fast | Process async |
| Idempotent | Dedupe by event id |
| Replay safe | Provider retries delivery |
| Order independence | Events may arrive out-of-order |
7. Designing Refund Processing
| Aspect | Detail |
|---|---|
| Full / partial | Track type |
| Reason code | For analytics + compliance |
| Reverse fulfillment | Revoke service / inventory |
| Approval flow | Threshold-based admin approval |
| Disputes / chargebacks | Evidence submission flow |
8. Designing Usage-Based Billing
| Element | Detail |
|---|---|
| Metering events | Idempotent capture |
| Aggregation | Daily rollup per metric |
| Tiered / volume / graduated | Pricing models |
| Tools | Stripe Metered, Metronome, Orb |
| Real-time meters | For UI display |
9. Designing Payment Security
| Practice | Detail |
|---|---|
| PCI scope reduction | Tokenization, hosted fields |
| No PAN storage | Token only |
| 3DS for high-risk | Liability shift |
| Velocity checks | Card / IP / email |
| CVV not stored | Even hashed |
10. Designing Multi-Currency Support
| Element | Detail |
|---|---|
| Store currency | Always with amount |
| Minor units | Integer cents; avoid float |
| FX rate | Locked at transaction time |
| Settlement currency | Provider converts |
| Display vs charge | May differ |
11. Designing Payment Reconciliation
| Step | Detail |
|---|---|
| Daily payout report | From provider |
| Match transactions | Internal vs gateway |
| Unreconciled queue | Investigate |
| Fees breakdown | Per transaction |
| Accounting export | QuickBooks / NetSuite |
12. Designing Fraud Detection
| Tool | Detail |
|---|---|
| Stripe Radar / Adyen RevenueProtect | Built-in ML |
| Sift / Signifyd / Forter | Specialized |
| Velocity rules | Same card N times / hour |
| Device fingerprint | Detect botnets |
| 3DS step-up | For risky transactions |
| Allow / block lists | Per email / BIN / country |