Verificado el codigo/README real de los dos unicos paquetes de Medusa
que aparecen buscando 'PayU' (@tax1driver/medusa-payu y
medusa-plugin-payu de rigby-sh, este ultimo archivado desde
2025-03-21): ambos usan la terminologia de la API de PayU Polonia/CEE
(clientId/posId/secondKey, OAuth), no la de PayU LatAm
(apiLogin/apiKey/accountId, developers.payulatam.com, la que cubre
Colombia). 'PayU' es una marca compartida por dos productos distintos.
La decision de negocio (PayU como proveedor) se mantiene -- cambia la
via tecnica: integracion via modulo de pago custom
(AbstractPaymentProvider de Medusa) contra la API real de PayU LatAm,
mismo tipo de esfuerzo que EnvioClick, no instalacion de plugin.
De paso, documenta las shipping options ya creadas y verificadas en
produccion (stock location, fulfillment set, service zone Colombia,
shipping option de 5.000 COP) incluyendo el paso no documentado que
las dejaba invisibles para el Store API (vinculo a sales channel).
Dato de negocio real del usuario: cuentas disponibles son Davivienda,
Lulo Bank y Banco de Bogota -- ninguna Bancolombia ni Nequi.
Verificado el mismo dia: Wompi exige cuenta Bancolombia o al menos
Nequi solo para REGISTRARSE como comercio (aunque la liquidacion
despues pueda ir a cualquier banco) -- ninguno de los bancos
disponibles califica sin abrir una cuenta nueva. PayU solo exige
cuenta bancaria colombiana a nombre del comercio, sin banco
especifico, y ya soporta PSE + Nequi + Daviplata para el cliente sin
importar el banco del comercio -- cubre exactamente lo que se pidio
(PSE + Nequi 'y demas bancos').
Estado pasa de propuesta a aceptada. Wompi se deja documentado como
deuda a reevaluar si en el futuro se abre cuenta Bancolombia/Nequi --
no se descarta por limitacion tecnica del plugin, solo por el
requisito de registro actual.
# 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,127 @@ 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 como proveedor de pago (negocio) se mantiene. La vía
técnica cambió el 2026-08-29 — ver nota de implementación al final de
este documento: ningún plugin comunitario de Medusa sirve para PayU
LatAm, hace falta un módulo de pago custom. Wompi queda descartado por
el requisito de registro Bancolombia/Nequi, no por limitación técnica.
**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 (`apiLogin`, `apiKey`, `merchantId`,
`accountId` — terminología real de la API de PayU LatAm, ver nota de
implementación) — nunca generadas ni asumidas por mí.
- Escribir el módulo de pago custom para PayU LatAm (no instalar un
plugin — no existe ninguno real para esta API, ver nota de
implementación).
## 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** — **elegido** (proveedor de negocio; integración técnica ahora es custom, ver nota de implementación) | 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 | Ningún plugin de Medusa real sirve para su API LatAm (`apiLogin`/`apiKey`/`accountId`) — los dos paquetes que parecían encajar por nombre son en realidad para PayU Polonia/CEE (`clientId`/`posId`/`secondKey`), uno de ellos archivado; requiere módulo de pago custom |
| **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
`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.
- El pago de PayU se implementa como módulo custom (`AbstractPaymentProvider`
de Medusa) contra la API real de PayU LatAm, no como instalación de
un plugin de terceros — más superficie propia para mantener, mismo
patrón de esfuerzo que ya se identificó para EnvíoClick en §2.
- Los webhooks de pago (a definir en el módulo custom, apuntando a la
URL de notificación real de PayU LatAm) 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.
## Nota de implementación (2026-08-29): shipping options creadas
Bloqueador de §1 resuelto en producción, verificado extremo a extremo
contra el Store API real (no solo creado en Admin):
- Stock location "Bodega principal ARI Shopping" (`sloc_01M15G3D1336V8WQW3VZQRP6AN`).
- Fulfillment set + zona de servicio "Colombia" (`geo_zone` tipo país, `co`).
- Provider `manual_manual` habilitado en la ubicación.
- Shipping option "Envío nacional estándar", tarifa fija $15.000 COP
(placeholder de negocio dentro del rango real de mercado
$12.000–$18.000 que dio el usuario, no un cálculo por peso/volumen —
eso es justamente lo que EnvíoClick resolvería más adelante),
vinculada al Default Shipping Profile y a la región Colombia/COP.
- **Paso no documentado en ningún lado y que rompía todo en silencio:**
la stock location tiene que estar vinculada al Sales Channel
(`/admin/stock-locations/{id}/sales-channels`) para que el Store API
devuelva la shipping option — sin esto, `GET /store/shipping-options`
devolvía `[]` vacío pese a que el fulfillment set, la zona de
servicio y el provider ya estaban bien configurados. Confirmado con
un carrito de prueba real (dirección `co` + `cart_id`) antes y
después del vínculo.
## Nota de implementación 2 (2026-08-29): corrección — no existe plugin real para PayU LatAm
Antes de instalar nada se verificó el código/README real de los dos
únicos paquetes de Medusa que aparecen buscando "PayU" — misma
disciplina que ya aplicó ADR 0006 al plugin de Meilisearch, esta vez
con un resultado distinto: **ninguno de los dos sirve.**
- `@tax1driver/medusa-payu`: opciones de configuración `clientId`,
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
gitea-actions
devops