Stripe Integration Lessons From 5 Real Products

Stripe's documentation is excellent. Their API is well-designed. Their developer experience is among the best in any third-party service. And yet, integrating payments across multiple products with different billing models taught me lessons that no documentation covers.

Lesson 1: Webhooks Are the Real Integration

The Stripe API handles creating charges and subscriptions. Webhooks handle everything else: subscription renewals, failed payments, refunds, disputes, payout completions. The webhook handler is where the real complexity lives.

My webhook handler for each product processes dozens of event types. Each event type triggers a specific business logic path: update the user's subscription status, send a notification, adjust access permissions, log the transaction. A missed webhook or a mishandled event means a user's experience diverges from reality.

The critical rule: make webhook handlers idempotent. Stripe may send the same event multiple times. If your handler creates a duplicate entry each time, you'll have inconsistent data. Process each event exactly once by tracking event IDs.

Lesson 2: Subscription States Are Complex

A Stripe subscription isn't simply "active" or "cancelled." It can be: active, past_due (payment failed but grace period applies), incomplete (initial payment pending), trialing, cancelled, unpaid, or paused.

Each state requires different product behavior. A past_due subscriber should probably still have access (the payment might retry successfully). An unpaid subscriber should lose access. A trialing subscriber needs to see upgrade prompts.

Mapping Stripe states to product access levels is a state machine that needs careful design. The common mistake is treating subscriptions as binary (active/inactive) and discovering edge cases when users complain about lost access.

Lesson 3: Multi-Currency Requires Planning

Serving European, UK, and US customers means handling euros, pounds, and dollars. Stripe handles the currency conversion, but the product needs to display prices in the right currency, store transactions in the original currency, and handle refunds in the payment currency.

The pricing strategy is also currency-dependent. €10/month and $10/month aren't equivalent, because currency conversion makes one cheaper than the other. I set prices per currency rather than converting from a base currency.

Lesson 4: Marketplace Payments Are a Different Beast

Babonbo's payment model (families pay, providers receive payouts minus a platform fee) uses Stripe Connect. Connect is Stripe's most complex product. Onboarding providers, handling split payments, managing payouts, and dealing with international transfer requirements add layers of complexity that simple charge-based products don't have.

The onboarding flow for Connect accounts requires identity verification, bank account details, and compliance documentation that varies by country. The provider experience during onboarding directly affects supply-side conversion.

Lesson 5: Test Mode Is Not Production

Stripe's test mode is excellent for development. It's not a perfect simulation of production. Test mode doesn't simulate: webhook delivery delays, bank processing times, currency conversion fees, dispute flows, or the specific errors that occur with real cards in real countries.

Always test the full payment flow with real cards (Stripe provides test cards, but also test with actual small transactions) before launch. The $1 test charge that reveals a real production issue is the best dollar you'll spend.

The Meta-Pattern

Across all products, I've standardized: one Stripe account, separate products/prices per application, shared webhook handling patterns, consistent subscription state mapping, and centralized payment event logging.

This standardization means adding payment to a new product takes hours, not days. The patterns are proven. The edge cases are handled. The monitoring is in place.