Full Checkout with Medusa, Stripe, and React: End-to-End Architecture

In a Medusa and Stripe integration, the Medusa backend acts as an intermediary between the frontend and Stripe. The client never calls Stripe directly with API credentials. Instead, Medusa creates a payment session on behalf of the cart and returns to the frontend the information needed for Stripe.js to confirm the payment without exposing secret keys.

The complete flow has five steps: create the cart, add items and a shipping address, select a shipping method, initialize payment sessions, and confirm the payment. The order is created in Medusa automatically upon receiving the Stripe confirmation via webhook. Each step has its own REST endpoint in the Medusa API.

The official Stripe plugin for Medusa is configured in `medusa-config.js` with the Stripe secret key and the webhook secret. Medusa automatically registers the webhook endpoint at `/stripe/hooks` and handles signature verification. There is no need to implement the webhook handler manually.

Once installed, Stripe appears as a payment option in all regions where it is enabled. Regions control which payment providers are available, which currency is used, and which taxes apply. A cart in the Mexico region uses MXN; one in the US region uses USD, and Stripe handles both currencies without changes on the frontend.

When initializing checkout, the frontend calls `POST /store/carts/:id/payment-sessions`. Medusa creates a payment session with Stripe, which internally creates a PaymentIntent and returns the `client_secret`. That secret is all the frontend needs for Stripe.js to confirm the payment from the browser.

The `client_secret` is never stored in the product database and never logged. It is valid for 24 hours and only serves to confirm that specific payment. If the cart changes — the user adds or removes items — the payment session must be updated so the PaymentIntent amount stays correct.

The most frequent errors in checkout are: card declined, session expired, and network interruption between the payment step and the order completion step. For a declined card, Stripe returns a typed error in the `confirmCardPayment` response — show it to the user and let them retry with a different card without resetting the cart.

For an expired session, call `createPaymentSessions` again to get a new `client_secret`. For a network interruption, the Stripe webhook guarantees that Medusa receives the confirmation even if the frontend never called `carts.complete`. The order status can be checked using the customer email or the cart ID.