Checkout completo con Medusa, Stripe y React: arquitectura de extremo a extremo

Cómo conectar Medusa como backend de ecommerce con Stripe como procesador de pagos y un frontend en React, desde el carrito hasta la orden confirmada.

Read in English

La arquitectura del flujo de checkout

En una integración de Medusa con Stripe, el backend de Medusa actúa como intermediario entre el frontend y Stripe. El cliente nunca llama a Stripe directamente con credenciales de API; en cambio, Medusa crea una payment session en nombre del carrito y devuelve al frontend la información necesaria para que Stripe.js confirme el pago sin exponer claves secretas.

El flujo completo tiene cinco pasos: crear el carrito, agregar items y dirección de envío, seleccionar método de envío, inicializar las payment sessions y confirmar el pago. La orden se crea en Medusa automáticamente al recibir la confirmación de Stripe vía webhook. Cada paso tiene su endpoint REST en la API de Medusa.

Configurar el plugin de Stripe en Medusa

El plugin oficial de Stripe para Medusa se configura en `medusa-config.js` con la clave secreta de Stripe y el webhook secret. Medusa registra automáticamente el endpoint de webhook en `/stripe/hooks` y se encarga de verificar las firmas. No hay que implementar el webhook handler manualmente.

Una vez instalado el plugin, Stripe aparece como opción de pago en todas las regiones donde esté habilitado. Las regiones controlan qué payment providers están disponibles, qué moneda se usa y qué impuestos aplican. Un carrito en la región de México usará MXN; uno en Estados Unidos usará USD, y Stripe maneja ambas monedas sin cambios en el frontend.

Payment sessions: el puente entre Medusa y Stripe

Al inicializar el checkout, el frontend llama a `POST /store/carts/:id/payment-sessions`. Medusa crea una payment session con Stripe, que internamente crea un PaymentIntent y devuelve el `client_secret`. Ese secret es lo único que el frontend necesita para que Stripe.js confirme el pago desde el navegador del usuario.

El `client_secret` nunca se guarda en base de datos del producto y nunca se registra en logs. Es válido por 24 horas y solo sirve para confirmar ese pago específico. Si el carrito cambia (el usuario agrega o quita items), hay que actualizar la payment session para que el amount del PaymentIntent sea correcto.

Inicializar payment sessions y confirmar el pago con Stripe Elements.

// 1. Inicializar payment sessions en el carrito
const { cart } = await medusaClient.carts.createPaymentSessions(cartId);

const stripeSession = cart.payment_sessions?.find(
  (s) => s.provider_id === 'stripe',
);

if (!stripeSession) throw new Error('Stripe session not available');

const clientSecret = stripeSession.data.client_secret as string;

// 2. Seleccionar Stripe como provider activo
await medusaClient.carts.setPaymentSession(cartId, {
  provider_id: 'stripe',
});

// 3. Confirmar el pago con Stripe.js
const { error } = await stripe.confirmCardPayment(clientSecret, {
  payment_method: { card: cardElement },
});

if (error) throw new Error(error.message);

// 4. Completar la orden en Medusa
const { type, order } = await medusaClient.carts.complete(cartId);

if (type === 'order') {
  router.push(`/orders/${order.id}`);
}

Manejo de errores y reintentos en el checkout

Los errores más frecuentes en el checkout son: tarjeta rechazada, sesión expirada y red interrumpida entre el paso de pago y el paso de completar la orden. Para tarjeta rechazada, Stripe devuelve un error tipado en la respuesta de `confirmCardPayment`; hay que mostrarlo al usuario y permitirle reintentar con otra tarjeta sin reiniciar el carrito.

Para sesión expirada, hay que llamar de nuevo a `createPaymentSessions` y obtener un nuevo `client_secret`. Para la red interrumpida, el webhook de Stripe garantiza que Medusa reciba la confirmación aunque el frontend no haya podido llamar a `carts.complete`. El estado de la orden se puede consultar por el email del cliente o el ID del carrito.

Más artículos

Volver a artículos

Plataformas de pago en México: Stripe, Conekta, Mercado Pago y OpenPay

Comparativa técnica y comercial de las cuatro plataformas más usadas para aceptar pagos en proyectos digitales mexicanos.

3 de junio de 2026

7 min de lectura

Plataformas de envíos en México: Skydropx, EnviosPerros, Pakke y Enviame

Cómo elegir entre los principales agregadores de paquetería para ecommerce en México según volumen, operación y necesidades técnicas.

3 de junio de 2026

7 min de lectura

CMS headless en 2026: PayloadCMS, Strapi, Sanity y Directus

Qué CMS headless elegir según el tipo de proyecto, el control técnico que necesitas y cómo planeas modelar el contenido.

3 de junio de 2026

8 min de lectura