diff --git a/workloads/docs-portal/docs/decisiones/0009-checkout-real.md b/workloads/docs-portal/docs/decisiones/0009-checkout-real.md index 2f682f7..ada1c55 100644 --- a/workloads/docs-portal/docs/decisiones/0009-checkout-real.md +++ b/workloads/docs-portal/docs/decisiones/0009-checkout-real.md @@ -1,7 +1,7 @@ # 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 +**Estado:** aceptada — proveedor de pago decidido (PayU, §3); +implementación real (credenciales, shipping options, código) pendiente **Fecha:** 2026-08-28 ## Contexto @@ -101,41 +101,76 @@ tiene ninguna shipping option que ofrecer. 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 +## 3. Decisión de proveedor — PayU -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: +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**. -- ¿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í. +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`) | 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 | +| **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 (si se procede, una vez elegido el proveedor) +## 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. -- 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 +- 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`. -- 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. +- 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.