Stripe Payments Highlights Summary

Every highlight bullet from the 12 pages in this section, gathered on one page and grouped by the page it came from.

Getting Started with Stripe

• Three packages, stripe for server, stripe-js and react-stripe-js for client
• Never import the server stripe SDK inside a client component
• Publishable key needs the NEXT_PUBLIC_ prefix to reach the browser
• Call loadStripe at module scope to avoid recreating the instance
• Elements provider initializes Stripe.js and shares it via React Context
• Pin apiVersion on the server SDK to avoid surprise breaking changes

Stripe Checkout Sessions

• Create sessions server-side via stripe.checkout.sessions.create, then redirect to the hosted URL
• Stripe replaces {CHECKOUT_SESSION_ID} in success_url with the real session ID
• Choose mode payment, subscription, or setup for one-time, recurring, or card-saving
• Never trust the success page alone, verify payment via webhooks or session retrieval
• session.url expires after 24 hours, so always generate a fresh session
• redirect throws NEXT_REDIRECT internally, do not swallow it in try/catch

Payment Intents (Custom Payment Flow)

• Server creates a PaymentIntent, returning a client_secret for browser confirmation
• Always call elements.submit before confirmPayment to validate fields early
• automatic_payment_methods picks the best methods per currency and customer location
• Use redirect if_required to stay on the page after success
• Force an Elements remount with key when clientSecret changes per amount
• Amounts use the smallest currency unit, 2999 means 29.99 USD

Payment Element & Card Element

• PaymentElement renders all enabled methods dynamically, CardElement handles cards only
• Appearance API styles Elements via theme, variables, and rule selectors
• Layout option controls tabs, accordion, or auto presentation of methods
• PaymentElement requires a clientSecret from a PaymentIntent or SetupIntent
• fields.billingDetails set to never lets you collect data yourself
• Custom fonts need the Elements fonts option since iframes ignore CSS

Subscriptions

• Subscriptions combine three objects, Product, Price, and Subscription per customer
• Checkout mode subscription auto-creates the Customer, Subscription, and first payment
• payment_behavior default_incomplete keeps status incomplete until client confirms first PaymentIntent
• Never grant access on redirect alone, verify via subscription webhooks
• cancel_at_period_end keeps access until period ends, listen for deleted event
• Trials set status trialing, delay charges, and create a $0 invoice

Stripe Webhooks

• constructEvent verifies the stripe-signature header against the raw body bytes
• Read the body with request.text, never request.json, or verification breaks
• Track processed event IDs for idempotency since Stripe retries deliveries
• Return a 2xx within 10 seconds, defer slow work asynchronously
• Cast event.data.object to specific types based on event.type
• Use headers from next/headers in App Router Route Handlers

Customer Portal

• Generate portal sessions with stripe.billingPortal.sessions.create and redirect using the returned url
• Look up the stripeCustomerId after authenticating before creating a portal session
• Configure available portal features in the Stripe Dashboard or programmatically via configurations.create
• Use flow_data to deep-link customers directly to actions like subscription_cancel
• Portal URLs expire within minutes, so never store or cache them
• Handle customer.subscription.updated and deleted webhooks to keep your database synced

Stripe React Hooks

• useStripe and useElements return null until Stripe.js finishes loading asynchronously
• Both hooks must run inside a component wrapped by the Elements provider
• Compose built-in hooks into custom hooks like useCheckout to reduce form boilerplate
• Avoid destructuring stripe or elements into later closures since references go stale
• Wrap the consumer onSuccess callback in useCallback to avoid recreating handlePayment
• Derive boolean flags like isActive and isPastDue from fetched subscription status

Stripe with Server Actions

• Server Actions keep the Stripe secret key off the client entirely
• useActionState tracks pending state and passes prevState to the action
• Validate FormData with Zod since client-side checks can be bypassed
• Call redirect outside try/catch or re-throw the NEXT_REDIRECT error
• revalidatePath refreshes server components after subscription cancel or resume
• Discriminated union action results make success and error states type-safe

Building a Pricing Page

• Fetch products and prices from Stripe so the page stays synced
• Product metadata stores features, highlighted, order, and show_on_pricing as strings
• revalidate 3600 enables ISR so price changes appear within an hour
• Monthly annual toggle switches between two Price objects on one Product
• The free tier is a hardcoded PricingTier with null prices linking to signup
• unit_amount is number or null, always null-check for metered or tiered pricing

Error Handling & Edge Cases

• Client StripeError and server Stripe.errors.StripeError have separate type hierarchies but similar categories
• Map raw error types to user-friendly messages, never expose technical details in production
• Retry only transient api_error, api_connection_error, and rate_limit_error, never card_error
• Treat requires_action as in-progress 3D Secure, not as payment failure
• Pass idempotencyKey so retried requests never create duplicate charges
• Use redirect if_required so confirmPayment redirects only for methods that need it

Testing Stripe Integration

• Test mode sk_test keys create sandbox data with no real charges
• Mock the Stripe SDK with vi.fn to isolate business logic
• Use dynamic await import inside tests so vi.mock hoisting takes effect
• Stripe CLI listen forwards events locally and supplies its own whsec secret
• Test cards trigger success, decline, or 3D Secure flows deterministically
• Playwright must use frameLocator to reach Stripe Elements inside iframes