Payment Integration Platform
Stripe event-driven: checkout, subscriptions, and lifecycle management
The product needed to support recurring payments with multiple plans, real-time upgrades/downgrades, and automatic delinquency recovery.
- 01Ensuring idempotency in Stripe webhook processing (events can arrive duplicated)
- 02Synchronizing subscription state between Stripe and the local database without inconsistency
- 03Managing plan transitions (upgrade/downgrade) with correct proration
- 04Recovering failed payments with intelligent retry without spamming the customer
Event-driven via webhooks with idempotency
Each Stripe event is processed exactly once using the event ID as an idempotency key in the database. Guarantees consistency even with Stripe retries.
Local state as the source of truth for the application
The application maintains its own subscription model synchronized via webhooks. This allows fast queries without dependence on Stripe API latency.
Checkout Session vs. Payment Intent
Checkout Session for new flows (UI hosted by Stripe, smaller PCI surface). Payment Intent only for automatic renewals already authorized.
Maintaining a local duplicate state requires periodic reconciliation with the Stripe API to detect drift. A daily reconciliation job was sufficient for the current volume.
FastAPI receives Stripe webhooks with HMAC signature verification. Each event type has a dedicated handler. Subscription state saved in PostgreSQL with status enum (active, past_due, canceled, trialing).
Full Stripe integration — webhooks, automated checkout, subscription management, and failed payment recovery.
- ›Testing webhooks locally with Stripe CLI before production saves hours of debugging
- ›Logging the full event payload (truncated) makes payment dispute auditing easier
- ›Implementing a webhook delivery log allows manual reprocessing when needed