|
|
|
@@ -0,0 +1,176 @@
|
|
|
|
|
# ADR 0009 — Checkout real (pago en línea + envíos) para ARI Shopping
|
|
|
|
|
|
|
|
|
|
**Estado:** aceptada — proveedor de pago decidido (PayU, §3);
|
|
|
|
|
implementación real (credenciales, shipping options, código) pendiente
|
|
|
|
|
**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:
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
{
|
|
|
|
|
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 de proveedor — PayU
|
|
|
|
|
|
|
|
|
|
Dato de negocio real que decidió esto (aportado por el usuario,
|
|
|
|
|
2026-08-28): las cuentas bancarias disponibles son Davivienda, Lulo
|
|
|
|
|
Bank y Banco de Bogotá — **ninguna es Bancolombia ni Nequi**.
|
|
|
|
|
|
|
|
|
|
Verificado contra fuentes reales el mismo día (no memoria):
|
|
|
|
|
|
|
|
|
|
- **Wompi exige cuenta Bancolombia o, como mínimo, cuenta Nequi para
|
|
|
|
|
poder registrarse como comercio** (modelo Agregador) — confirmado
|
|
|
|
|
contra el reglamento de comercios de Wompi y su centro de soporte.
|
|
|
|
|
La liquidación de ventas sí puede ir después a cualquier banco
|
|
|
|
|
colombiano, pero la puerta de entrada al registro sigue siendo
|
|
|
|
|
Bancolombia/Nequi. Con los bancos disponibles hoy, esto exigiría
|
|
|
|
|
abrir una cuenta Nequi nueva solo para poder registrarse — paso
|
|
|
|
|
extra evitable.
|
|
|
|
|
- **PayU solo exige "cuenta bancaria colombiana a nombre del
|
|
|
|
|
comercio"**, sin banco específico — Davivienda, Lulo Bank o Banco de
|
|
|
|
|
Bogotá califican igual, sin pasos previos. Además ya soporta **PSE**
|
|
|
|
|
(transferencia desde cualquier banco colombiano del cliente, sin
|
|
|
|
|
relación con el banco del comercio), **Nequi** y **Daviplata** como
|
|
|
|
|
métodos de pago para los clientes vía redirección — cubre exactamente
|
|
|
|
|
los métodos que se pidieron (PSE + Nequi "y demás bancos") sin que
|
|
|
|
|
la cuenta bancaria propia del comercio sea Bancolombia.
|
|
|
|
|
|
|
|
|
|
**Decisión:** PayU, vía el plugin comunitario `@tax1driver/medusa-payu`
|
|
|
|
|
(compatibilidad declarada con Medusa 2.4.0+, cubre nuestra versión
|
|
|
|
|
2.18.0). Wompi queda descartado por el requisito de registro
|
|
|
|
|
Bancolombia/Nequi, no por limitación técnica del plugin en sí.
|
|
|
|
|
|
|
|
|
|
**Pendiente antes de implementar (no resoluble en este ADR):**
|
|
|
|
|
|
|
|
|
|
- Registro real de comercio en PayU (persona natural o jurídica —
|
|
|
|
|
jurídica pide NIT, representante legal y estados financieros
|
|
|
|
|
básicos) y credenciales reales (API keys, merchant ID, webhook
|
|
|
|
|
config) — nunca generadas ni asumidas por mí.
|
|
|
|
|
- Verificar el código fuente real de `@tax1driver/medusa-payu` en el
|
|
|
|
|
tag exacto a instalar antes de confiar en su documentación, misma
|
|
|
|
|
disciplina que ya destapó desviaciones reales en el plugin de
|
|
|
|
|
Meilisearch (ADR 0006).
|
|
|
|
|
|
|
|
|
|
## 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`) — **elegido** | Compatibilidad declarada explícitamente con Medusa 2.4.0+ (cubre 2.18.0); solo exige cuenta bancaria colombiana a nombre del comercio, sin banco específico (encaja con Davivienda/Lulo Bank/Banco de Bogotá); soporta PSE + Nequi + Daviplata para el cliente sin importar el banco del comercio | 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 | Exige cuenta Bancolombia o, como mínimo, Nequi solo para **registrarse** como comercio — ninguno de los bancos disponibles (Davivienda/Lulo Bank/Banco de Bogotá) califica sin abrir una cuenta nueva; además, sin versión de Medusa documentada ni actividad reciente visible en el plugin |
|
|
|
|
|
| **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
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
- Al ser `@tax1driver/medusa-payu` un plugin comunitario (no de
|
|
|
|
|
primera clase como Stripe), 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
|
|
|
|
|
ni asumir que "compatibilidad declarada" significa "verificado en
|
|
|
|
|
este proyecto".
|
|
|
|
|
- Los webhooks de pago (registrados por el plugin en
|
|
|
|
|
`/hooks/payment/payu`) 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`.
|
|
|
|
|
- Se acepta como deuda: si en el futuro se abre una cuenta Bancolombia
|
|
|
|
|
o Nequi, Wompi (liquidación más directa en COP) vuelve a ser una
|
|
|
|
|
opción válida a reevaluar — no se descarta por limitación técnica,
|
|
|
|
|
solo por el requisito de registro actual.
|
|
|
|
|
- Revertir esta decisión 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.
|
devops
gitea-actions