ADR-013: pasarela del demo, Stripe en modo de prueba más pasarela falsa
Aceptado el 10/11/2026 por Andrés (Stripe en su ambiente de prueba).
Contexto
El demo debe permitir comprar desde una tienda y ver la saga completa. Andrés ya tiene Stripe.
Decisión
payment-service define un puerto de pasarela con dos implementaciones, elegidas por configuración:
| Implementación | Uso |
|---|---|
| Stripe en modo de prueba | Compra real de punta a punta desde la tienda, con tarjetas de prueba |
| Pasarela falsa con perillas | Escenarios 4 y 5 y el pipeline: rechazos, webhooks duplicados o perdidos, de forma determinista y sin red |
Cómo encaja en la saga
- La tienda tokeniza la tarjeta en el navegador con el componente de Stripe. La capa nunca ve la tarjeta.
- La orden viaja con
payment.tokenigual al identificador del medio de pago que entrega Stripe. payment-servicecrea y confirma el cobro en Stripe, usando elorderIdcomo llave de idempotencia.- Stripe avisa el resultado por webhook firmado al grupo
callbacksdel gateway. payment-serviceverifica la firma, deduplica y publicaPaymentApprovedoPaymentRejected.
Llaves y mínimo privilegio (11/11/2026)
payment-service no usa la llave secreta de acceso total. Usa una llave restringida (rk_test_), llamada payment-service en la sandbox de la cuenta "Andes Retail", con solo dos permisos:
| Permiso de Stripe | Nivel | Para qué |
|---|---|---|
| Payment Intents | Write | Crear y confirmar el cobro con PaymentRequested; consultar su estado al conciliar (Write incluye Read) |
| Charges and Refunds | Write | Reembolsar con RefundRequested, la compensación de la saga. Stripe no separa reembolsos de cargos: es el mínimo disponible |
Todo lo demás queda en None. No necesitan permiso de la llave:
- Verificar webhooks: usa el secreto de firma
whsec_, otro valor. - Registrar el destino del webhook: configuración única en el panel, no la hace el servicio.
- Tokenizar la tarjeta: la hace el navegador con la llave publicable.
La llave de acceso total queda solo para administración en el panel. En producción el criterio es el mismo, con una llave restringida por servicio y rotación desde el gestor de secretos.
Supuesto por confirmar con la primera compra de prueba: que confirmar el cobro con un medio de pago creado en el navegador no exija también Payment Methods en Read. Si falla con un error de permisos, se agrega ese permiso y nada más.
Qué se sacrifica
- Tarjetas que exigen autenticación adicional (3-D Secure) no se soportan en el demo: se tratan como rechazo. En producción requieren un paso más en el navegador.
- Dependencia de un servicio externo en el demo en vivo; por eso la pasarela falsa sigue siendo la del pipeline.
Por verificar en la documentación de Stripe al implementar
- Parámetros exactos para crear y confirmar el cobro en el servidor sin redirecciones.
- Soporte de pesos colombianos en la cuenta; si no, el demo usa dólares.
- Nombres de los eventos de webhook de cobro exitoso y fallido, y formato de la firma.
- Uso de un entorno aislado de pruebas (sandbox) dentro de la cuenta existente.
Nota del 15/11/2026
El ADR-035 complementa el paso 1 de "Cómo encaja en la saga": además del componente de Stripe en la página de pago (camino incrustado, con la llave publicable), la tarjeta se puede escribir en la página de Stripe (camino alojado, Checkout en modo setup, con una llave restringida en el Worker). Un interruptor elige el camino. En los dos la orden lleva payment.token = pm_...; los pasos 2 a 5 y las llaves de payment-service no cambian.