Payments

Situation Detection

Universal Rules

Never store card data. Use provider-hosted checkout or tokenization. PCI compliance burden explodes the moment raw card numbers touch your server.

Webhooks are truth. Client-side success callbacks lie. A payment succeeded only when your webhook confirms it. Design for webhook-first verification.

Test mode exists for a reason. Use test cards, simulate failures, verify webhook handling. Production surprises cost real money and real customers.

Pricing psychology: $9.99/mo feels cheaper than $120/year, but annual retention is 2-3x higher. Default to annual with monthly option, not the reverse.

Provider Quick Compare

See providers.md for detailed comparison.

Integration Checklist

Before going live:

• [ ] Webhook endpoint secured and verified
• [ ] Idempotency keys on all charges
• [ ] Failure states handled (declined, expired, insufficient)
• [ ] Receipts and invoices configured
• [ ] Refund flow tested
• [ ] Subscription lifecycle events handled (upgrade, downgrade, cancel)
• [ ] Currency handling explicit (store in cents/smallest unit)

Red Flags

• Storing CVV anywhere, ever → Instant PCI violation
• Trusting client-side payment confirmation → Fraud vector
• No retry logic for failed webhooks → Lost transactions
• Hardcoding prices in frontend → Easy manipulation
• Missing cancel_at_period_end handling → Angry customers

When to Load More