apps-registry/workloads/docs-portal/docs/decisiones/0009-checkout-real.md

ADR 0009 — Checkout real (pago en línea + envíos) para ARI Shopping

Estado: propuesta — pendiente de decisión de negocio (§3) antes de implementar Fecha: 2026-08-28

Contexto

El carrito hoy no completa una transacción real: arma el pedido en el cliente y lo cierra con un botón "Continuar por WhatsApp" (components/layout/navbar.tsx, mobile-add-to-cart.tsx) — un placeholder intencional, no un bug. El diálogo de cuenta ya lo admite explícitamente ("El inicio de sesión quedará conectado al backend headless. Mientras tanto..."). Ni checkout ni auth de clientes tienen ADR previo ni intento de implementación en el historial de git de ningún repo del lab — este es terreno nuevo.

Investigación previa a este ADR (2026-08-28, confirmado contra código real y documentación oficial vigente, no memoria de entrenamiento — misma disciplina que ADR 0006):

• Pagos: commerce-backend/medusa-config.ts no registra ningún provider de pago — el único módulo configurado hoy es @medusajs/medusa/file (storage S3).
• Envíos: existe una sola región ("Colombia", COP), creada a mano vía Admin API durante el incidente de precios de agosto (incidente-medusa-precios-region-id-2026-08.md), no vía ningún script de seed — no existe ningún script de seed en el repo. No hay ninguna shipping option configurada en ningún lado. Sin esto el checkout no puede completarse aunque el pago ya funcione — es un prerequisito invisible, independiente del proveedor de pago elegido.
• Auth: cero código de cliente/login en todo el storefront (grep sobre lib/, app/, components/ sin resultados para customer/login/useAuth//store/customers). El módulo de auth/customer de Medusa viene incluido en el core — falta enteramente el lado del storefront, no el backend. Medusa soporta checkout como invitado, así que auth no bloquea checkout y puede secuenciarse por separado — fuera de alcance de este ADR.

1. Flujo de checkout real en Medusa v2 (Store API)

Confirmado contra docs.medusajs.com (2026-08-28): el flujo son 7 pasos encadenados — crear carrito → agregar items → dirección de envío → seleccionar método de envío (POST a la ruta de shipping method del carrito, requiere que ya exista al menos una shipping option) → payment collection → payment session → completar orden. Ningún paso es opcional; el paso de método de envío es exactamente el que hoy no tiene ninguna shipping option que ofrecer.

2. Estado real de soporte de pago en Medusa 2.18.0

• Stripe es de primera clase (@medusajs/medusa/payment-stripe, incluido en el core, no un plugin de terceros — a diferencia de la situación de Meilisearch en ADR 0006). Configuración mínima verificada:

  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [{
        resolve: "@medusajs/medusa/payment-stripe",
        id: "stripe",
        options: { apiKey: process.env.STRIPE_API_KEY },
      }],
    },
  }
  

  Env vars: STRIPE_API_KEY (siempre) y STRIPE_WEBHOOK_SECRET (obligatorio en producción). Tras configurar, hay que habilitar el provider en la región desde el Admin — un paso manual aparte, igual que ya pasó con la región misma.

• Bloqueador real de negocio, no técnico: Stripe no acepta cuentas de comercio registradas en Colombia. Confirmado contra stripe.com/global (2026-08-28) — Brasil y México sí están en la lista de países soportados para abrir cuenta, Colombia no aparece. La única vía sería registrar una entidad de negocio en un país soportado, fuera de alcance realista para este lab. Esto invalida a Stripe como opción pese a ser la integración técnicamente más simple y mejor documentada.

• Alternativas con presencia real en Colombia y algún plugin de Medusa existente:

  • PayU (@tax1driver/medusa-payu): el propio repo declara compatibilidad explícita con Medusa v2.4.0+ — cubre nuestra versión (2.18.0). Webhook auto-registrado en /hooks/payment/payu.
  • Wompi (medusa-payment-wompi-col, respaldado por Bancolombia, liquidación directa en COP): revisé el repo directamente (2026-08-28) y no documenta contra qué versión de Medusa se probó, ni tiene releases/actividad reciente visible — mayor riesgo de compatibilidad no verificada que PayU, aunque el encaje de negocio (banco local, moneda nativa) sea el más directo. Antes de elegirlo habría que repetir el nivel de verificación que ADR 0006 le hizo al plugin de Meilisearch: leer el código fuente real, no confiar en el README.

• Riesgo de red ya conocido, no nuevo: cualquier webhook de pago entra por la misma cadena Cloudflare → NPM → Traefik que ya causó un incidente real con otro servicio (incidente-cloudflared-504-quic-2026-08.md). Validar la entrega de webhooks en vivo antes de confiar en el flujo, no asumir que "funciona igual que todo lo demás".

3. Decisión pendiente — requiere input del usuario, no se puede resolver en este ADR

Este ADR no elige proveedor de pago porque la elección real depende de datos de negocio que no están en el código ni son míos para decidir:

• ¿Ya existe una cuenta bancaria/comercial en Colombia con la que abrir Wompi (Bancolombia) o PayU directamente?
• ¿Preferencia por comisión, tiempo de liquidación, o soporte en español de cada uno?
• Credenciales reales (API keys, webhook secrets) — nunca generadas ni asumidas por mí.

Opciones consideradas

Opción	A favor	En contra
Stripe	Integración core de Medusa, mejor documentada, configuración mínima	No acepta comercios registrados en Colombia — bloqueador de negocio, no técnico
PayU (@tax1driver/medusa-payu)	Compatibilidad declarada explícitamente con Medusa 2.4.0+ (cubre 2.18.0); presencia real en Colombia	Plugin comunitario, no de primera clase; requiere la misma verificación de código fuente que ya se le hizo al plugin de Meilisearch antes de confiar en él
Wompi (medusa-payment-wompi-col)	Liquidación directa en COP vía Bancolombia, el encaje de negocio más directo para un comercio colombiano	Sin versión de Medusa documentada ni actividad reciente visible — mayor riesgo de compatibilidad no verificada que PayU
Seguir con WhatsApp (no pago en línea)	Cero riesgo nuevo, cero dependencia externa	No resuelve el objetivo real (transacción completa sin intervención manual); no es checkout, es lo que ya existe hoy

Consecuencias (si se procede, una vez elegido el proveedor)

• Las shipping options son un prerequisito independiente del proveedor y deben configurarse primero — sin ellas ningún flujo de checkout completa, sea cual sea el pago.
• Cualquier plugin comunitario (PayU o Wompi) exige la misma disciplina de verificación que ya destapó desviaciones reales en el plugin de Meilisearch (ADR 0006, nota de implementación): leer el código fuente en el tag exacto que se va a instalar, no el README genérico.
• Los webhooks de pago deben validarse en vivo contra la cadena de red real del lab antes de confiar en el flujo, dado el precedente de incidente-cloudflared-504-quic-2026-08.md.
• Revertir esta decisión (una vez implementada) implica deshabilitar el provider en la región y volver al botón de WhatsApp — el carrito y el catálogo no cambian de forma, solo el paso final.