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.
Propuesta, no aceptada: investiga el estado real de Medusa 2.18.0 para
soportar checkout de verdad (hoy el carrito cierra por WhatsApp).
Verificado contra codigo real y documentacion oficial de Medusa
(2026-08-28): cero shipping options configuradas (bloqueador
independiente del proveedor de pago), Stripe es de primera clase en
Medusa v2 pero no acepta comercios registrados en Colombia
(confirmado contra stripe.com/global), PayU tiene compatibilidad
declarada con Medusa 2.4.0+, Wompi no documenta version de Medusa ni
actividad reciente.
Deja la eleccion de proveedor de pago explicitamente pendiente de
decision de negocio del usuario -- no es algo que se pueda resolver
en el codigo.
promo-backpacks.webp tenia el fondo punteado violeta/morado del
esquema arcoiris original, notado al confirmar el fix anterior de
Club ARI (el panel de texto ya paso a azul solido, pero la foto de al
lado seguia con su propio color viejo).
Sin herramienta de generacion de imagenes disponible, se reconstruye
el mismo efecto (fondo punteado + fotos estilo polaroid) con CSS
(radial-gradient azul sobre fondo amarillo, circulo decorativo azul)
y 3 fotos reales de producto ya existentes en public/images/products/
en vez de la foto compuesta vieja.
Dos leftovers del esquema original notados de pasada durante las
pruebas de ADR 0008 (fuera del alcance original de logo/buscador/
hero/tiles, pero mismo patron): la etiqueta 'Novedades' en
text-fuchsia-600 y la seccion 'Club ARI' con gradiente
cyan-500/blue-600/violet-600 + badge text-yellow-300.
Ambos pasan a los tokens de marca (ari-coral, ari-marino solido,
ari-coral-claro) -- ya no queda ningun gradiente ni color hardcodeado
del esquema arcoiris original en el home.
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 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** — **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
- 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.
- 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.
devops
gitea-actions