Designing flexible payment flows with Checkout Session

Summary

The post addresses the architectural challenge of taking a digital product business global while supporting localized tax, currencies, one-time purchases, subscriptions, and a branded embedded checkout. It recommends Checkout Sessions as the orchestration layer, with Stripe creating and managing the underlying Payment Intent while declarative parameters handle features such as Stripe Tax, Adaptive Pricing, subscriptions, and promotional codes. The implementation creates a session with ui_mode, mode, automatic_tax, adaptive_pricing, line items, and optional payment_intent_data, then passes the client secret to Stripe Elements for the Payment Element and Currency Selector. This approach supports localized payment methods and currency conversion without a backend rewrite, while direct Payment Intents remain appropriate when an application needs full control over carts, discounts, taxes, or its own checkout abstraction.

Context

Digital product businesses expanding beyond their initial markets need to support VAT, multiple currencies, one-time purchases, recurring subscriptions, and an embedded branded checkout while managing global commerce complexity.

Approach / What changed

Create a Checkout Session configured with declarative commerce parameters such as automatic_tax, adaptive_pricing, mode, line items, and optional payment_intent_data. Pass its client secret to Stripe Elements, render the Payment Element and Currency Selector, and complete the flow with stripe.initCheckout(). Use Payment Intents directly only when the business requires granular control over commerce logic or a custom checkout abstraction layer.

Takeaways

• Checkout Sessions act as a high-level orchestration layer, automatically creating and managing the underlying Payment Intent for a payment flow.
• The Payment Element displays payment methods based on customer location, currency, and transaction details; the Currency Selector can offer localized presentment currencies when Adaptive Pricing is enabled.
• Direct Payment Intents are intended for cases requiring self-managed line items, discounts, tax calculations, cart changes, or a platform's own checkout abstraction.

Related reading