id: 0005-stripe-payment-intents
type: decision
owner: justin
status: accepted
reviewed: 2026-10-02

0005 Charge with Stripe PaymentIntents from storefront-api

Context

The shop needs card payments, and later wallets, without card data touching our Workers. Stripe offers a hosted Checkout page or PaymentIntents confirmed in our own page with the Payment Element.

Decision

Checkout creates a PaymentIntent with the stripe package from storefront-api, using the secret key STRIPE_SECRET_KEY. The browser confirms it with the client secret. The order id goes in the intent's metadata and in the idempotency key, order-<id>.

Consequences

• The payment form is part of our page, and the payment methods are whatever is turned on in the Stripe dashboard (automatic_payment_methods).
• storefront-api holds the Stripe secret key, next to the public API.
• The order is paid only when Stripe says so, which needs a webhook.