Gateway de Pagos
Diseñé y desarrollé un gateway backend para integrar sistemas municipales con un proveedor externo de pagos QR. La solución desacopla los sistemas internos del contrato técnico del proveedor, normaliza la generación y seguimiento de pagos, procesa notificaciones asíncronas, permite conciliación operativa y brinda herramientas internas para administrar el ciclo de vida de una deuda o pago. El proyecto fue construido con NestJS, PostgreSQL y Docker, priorizando robustez, trazabilidad, seguridad, idempotencia y operación diaria por parte de equipos no técnicos.
Contexto
La municipalidad necesitaba integrar sus sistemas de gestión con un proveedor de pagos QR sin acoplar cada sistema interno al contrato específico del proveedor. El flujo requería generar códigos QR, registrar deudas, recibir notificaciones de pago, conciliar estados y brindar visibilidad operativa al equipo municipal. Además, la integración debía contemplar fallos de red, respuestas asincrónicas, reintentos, duplicados, trazabilidad y manejo seguro de datos sensibles.
Complejidad
Alta
Desarrollador backend líder / Arquitecto de software
La integración directa entre sistemas municipales y proveedor de pagos generaba varios riesgos: Alto acoplamiento con un contrato externo. Dificultad para manejar cambios del proveedor. Posibles duplicados ante reintentos o cortes de red. Procesamiento asincrónico de estados de pago. Necesidad de importar deudas en volumen. Falta de visibilidad operativa para usuarios internos. Requerimientos de trazabilidad sobre pagos, deudas y notificaciones. Manejo de datos sensibles dentro de un flujo crítico.
Se desarrolló un gateway backend modular que centraliza la comunicación con el proveedor de pagos QR y expone una API interna para los sistemas municipales. La solución permite: Registrar deudas individuales y por lotes. Generar y administrar pagos QR. Procesar notificaciones externas. Conciliar pagos y estados. Reintentar operaciones fallidas de forma controlada. Notificar eventos relevantes a sistemas internos. Operar el flujo desde un panel interno. Mantener auditoría y trazabilidad de acciones críticas.
Restricciones
- El gateway no es una aplicación de login ciudadano ni un portal público: funciona como capa backend de integración, consumida por sistemas municipales autorizados.
- No contiene lógica fiscal ni contable municipal.
- Depende del contrato vigente del proveedor de pagos.
- Los sistemas internos conservan sus propias reglas de negocio.
- Los datos sensibles requieren controles específicos de acceso y persistencia.
- Los cambios de esquema deben realizarse mediante migraciones controladas.
- La operación debe contemplar fallos de red, reintentos y eventos asincrónicos.
Arquitectura
La arquitectura se resolvió como un backend modular en NestJS, separado por responsabilidades funcionales. El sistema utiliza una base de datos relacional para persistir transacciones, lotes, estados, eventos y registros de auditoría. La comunicación con el proveedor externo se encapsula en una capa de integración, evitando que los sistemas municipales dependan directamente del contrato del tercero. Se incorporaron procesos programados para seguimiento de operaciones, conciliación, recuperación de estados y mantenimiento operativo. El gateway también incluye mecanismos de idempotencia, registro de intentos, notificaciones internas, validación de entrada, observabilidad y despliegue contenerizado.
Decisiones técnicas
- Usar NestJS con TypeScript para construir el backend principal.
- Organizar el sistema con arquitectura modular por capas.
- Usar PostgreSQL como base de datos relacional.
- Separar la capa de integración con el proveedor externo.
- Implementar mecanismos de idempotencia para evitar operaciones duplicadas.
- Registrar intentos y eventos relevantes para trazabilidad.
- Usar procesos programados para seguimiento, conciliación y mantenimiento.
- Separar migraciones del arranque normal de la aplicación.
- Contenerizar la solución para facilitar despliegue y mantenimiento.
- Exponer documentación técnica solo en entornos controlados.
Seguridad
- Autenticación de endpoints internos. Validación estricta de entrada en backend.
- Control de acceso a operaciones sensibles.
- Protección de datos personales y financieros.
- Auditoría de acciones relevantes. Redacción de información sensible en logs.
- Rate limiting sobre operaciones críticas. Separación de secretos y configuración por entorno.
- Validaciones defensivas sobre eventos externos.
- No exposición pública de herramientas operativas internas.
Resultado
El gateway permitió centralizar la integración de pagos QR y reducir el acoplamiento entre sistemas municipales y proveedor externo. El equipo municipal puede generar pagos, procesar lotes, revisar estados, conciliar diferencias y operar el flujo diario desde una herramienta interna. La solución mejoró la trazabilidad del ciclo de vida de los pagos, facilitó tareas de soporte y dejó una base técnica preparada para integraciones futuras con otros sistemas o proveedores.
Aprendizajes
En integraciones de pagos, la idempotencia no es opcional: es una condición básica de diseño. - Un gateway intermedio reduce el impacto de cambios en proveedores externos. - Los eventos asincrónicos requieren conciliación, auditoría y recuperación controlada. - Un panel operativo simple puede reducir mucho la dependencia del equipo técnico. - Separar integración externa, lógica de aplicación y operación interna mejora la mantenibilidad. - Los sistemas de pago deben diseñarse considerando fallos parciales, duplicados y estados inconsistentes. - La trazabilidad es tan importante como la generación del pago.
Mejoras futuras
Ampliar la conciliación automática con otros sistemas internos. - Mejorar reportes operativos para el equipo municipal. - Incorporar más alertas sobre estados inconsistentes. - Profundizar pruebas de contrato con ambientes de integración. - Automatizar más tareas de recuperación y soporte. - Evaluar esquemas de alta disponibilidad. - Mejorar tableros de monitoreo y métricas funcionales.