API CoDi del Banco de México

En esta publicación, explicaré cómo construí una API REST lista para producción que permite a empresas en México aceptar pagos digitales con cero comisiones por transacción y depósitos inmediatos. La API se integra con el sistema oficial de pagos CoDi del Banco de México (Banxico) y es completamente de código abierto bajo la licencia Apache 2.0.

Si quieres ir directamente al código, puedes visitar el repositorio de GitHub. También puedes explorar el sitio de documentación en vivoo probar el playground interactivo de la API.

¿Te gustaría implementar CoDi para tu negocio? Contáctame y te ayudaré a integrarlo.

Descripción del Proyecto

La API CoDi es una API REST de producción que resuelve un problema crítico para las empresas mexicanas: aceptar pagos digitales sin pagar altas comisiones por transacción. Los procesadores de pago tradicionales cobran entre 2-4% por transacción (más 16% de IVA), lo que puede impactar significativamente los márgenes de ganancia, especialmente para pequeñas empresas.

Al integrarse directamente con el sistema CoDi de Banxico, esta API permite a las empresas aceptar pagos desde cualquier cuenta bancaria mexicana a través de códigos QR o notificaciones push a aplicaciones bancarias móviles, con cero comisiones por transacción.

Aspectos Destacados del Proyecto

• Listo para Producción: API en vivo procesando pagos reales activamente
• Integración Gubernamental: Integración oficial con el sistema CoDi de Banxico
• Cero Comisiones: Sin comisiones por transacción, nunca
• Seguridad de Nivel Bancario: Firmas digitales RSA y autenticación por certificados
• Código Abierto: Licencia Apache 2.0, completamente transparente
• Documentación Completa: Playground interactivo, generadores de código y guías detalladas
• Mercado Mexicano: Construido específicamente para la infraestructura de pagos de México

¿Qué es CoDi?

CoDi (Cobro Digital) es el sistema oficial de pagos digitales del Banco Central de México, lanzado en 2019 para promover la inclusión financiera y proporcionar una alternativa moderna a los pagos en efectivo y con tarjeta.

Cómo Funciona CoDi

A diferencia de los procesadores de pago tradicionales, CoDi opera directamente a través del sistema bancario. Cuando un cliente realiza un pago CoDi, el dinero se transfiere instantáneamente desde su cuenta bancaria a la cuenta bancaria del comerciante, sin intermediarios que se lleven una comisión.

El sistema soporta dos métodos de pago:

• Pagos con Código QR: El cliente escanea un código QR con su aplicación bancaria para autorizar el pago
• Notificaciones Push: La solicitud de pago se envía directamente a la aplicación bancaria móvil del cliente

Beneficios Clave de CoDi

• Cero Comisiones por Transacción: Sin comisiones cobradas a comerciantes o clientes
• Transferencia Inmediata de Dinero: Fondos disponibles de inmediato
• Trazabilidad Completa: Rastro de auditoría completo de todas las transacciones
• Seguridad de Nivel Bancario: Protegido por las mismas medidas de seguridad que la banca en línea
• Compatibilidad Universal: Funciona con todos los bancos mexicanos

Arquitectura Técnica

La API CoDi está construida como una capa de middleware Node.js/Express que maneja la autenticación compleja y la comunicación con la infraestructura de pagos de Banxico, exponiendo una API REST simple a las aplicaciones cliente.

Componentes de la Arquitectura

El sistema consiste en varias capas clave:

1. Capa de API REST (Express.js): Maneja solicitudes entrantes, validación y respuestas
2. Capa de Autenticación: Gestiona firmas digitales RSA y validación de certificados
3. Capa de Integración con Banxico: Se comunica con los endpoints CoDi de Banxico
4. Arquitectura de Respaldo: Soporte de múltiples endpoints con lógica de reintento automático
5. Persistencia de Datos (Supabase): Almacena claves API, registros de pago y logs de auditoría
6. Sistema de Webhooks: Entrega confirmaciones de pago en tiempo real a aplicaciones cliente

Flujo de Solicitud

Esto es lo que sucede cuando una aplicación cliente solicita un pago:

1. El cliente envía una solicitud POST con detalles del pago (monto, descripción, etc.)
2. La API valida la solicitud y autentica usando la clave API
3. Los datos del pago se firman con el certificado RSA
4. La solicitud firmada se envía al sistema CoDi de Banxico
5. Banxico genera el código QR o envía la notificación push
6. La API almacena el registro de transacción en PostgreSQL
7. La respuesta se devuelve al cliente con el código QR o confirmación
8. Cuando el cliente paga, se envía una notificación webhook a la URL de callback del cliente

Características Principales

La API CoDi proporciona seis características principales, cada una diseñada para hacer que la integración de pagos digitales sea lo más simple posible mientras se mantiene seguridad y confiabilidad de nivel empresarial.

1. Generación de Pagos con Código QR

Genera códigos QR compatibles con CoDi que los clientes pueden escanear con cualquier aplicación bancaria mexicana. Los códigos QR son dinámicos, lo que significa que contienen toda la información del pago y pueden expirar después de un tiempo especificado.

• Rango de pago: $1 - $12,500 MXN por transacción
• Expiración personalizable (incluyendo sin expiración)
• Incluye números de referencia y descripciones personalizadas
• Código QR codificado en Base64 devuelto en la respuesta de la API

2. Notificaciones de Pago Push

Envía solicitudes de pago directamente a la aplicación bancaria móvil de un cliente usando su número de teléfono. El cliente recibe una notificación y puede autorizar el pago con un solo toque.

• Entrega instantánea a la aplicación bancaria del cliente
• No se requiere escaneo de código QR
• Perfecto para pagos remotos
• Actualizaciones de estado de pago en tiempo real

3. Consultas de Estado de Pago

Verifica el estado de cualquier pago usando su número de referencia único folioCoDi. Esto permite verificación de pago en tiempo real y seguimiento del historial de transacciones.

• Verificación de pago en tiempo real
• Búsqueda de historial de transacciones
• Capacidades de rastro de auditoría
• Información detallada del pago

4. Integración de Webhooks

Recibe notificaciones automáticas cuando se completan los pagos. Configura una URL de callback, y la API enviará datos de confirmación de pago a tu servidor cuando un cliente pague.

• Confirmaciones automáticas de pago
• URLs de callback configurables
• Firma segura de webhooks
• Lógica de reintento para entregas fallidas

5. Arquitectura de Seguridad

Las características de seguridad de nivel empresarial protegen tanto la API como tus datos de pago. Cada solicitud a Banxico está firmada digitalmente con certificados RSA, y todas las comunicaciones están encriptadas.

• Firmas digitales RSA (mínimo 2048 bits)
• Autenticación basada en certificados con Banxico
• Gestión de claves API a través de Supabase
• Registro de solicitudes/respuestas para rastros de auditoría
• Protección CORS con lista blanca de IPs
• Limitación de tasa (200 solicitudes por 15 minutos)
• Encabezados de seguridad Helmet.js

6. Documentación Interactiva

La documentación completa con herramientas interactivas hace que la integración sea sencilla, incluso para desarrolladores nuevos en el procesamiento de pagos.

• Especificación Swagger/OpenAPI 3.0
• Funcionalidad de prueba para todos los endpoints
• Guías de integración paso a paso en español
• Generadores de código para múltiples lenguajes
• Playground interactivo de API

Experiencia del Desarrollador

Una gran API necesita gran documentación y herramientas. La API CoDi incluye un sitio de documentación completo con características interactivas que hacen que la integración sea más rápida y la depuración más fácil.

Playground Interactivo de API

Prueba todos los endpoints de la API directamente desde tu navegador sin escribir ningún código. El playground incluye ejemplos prellenados y valida tus solicitudes en tiempo real.

Generadores de Código

Genera código de integración listo para usar en múltiples lenguajes de programación. Simplemente selecciona tu endpoint e idioma, y obtén ejemplos de código listos para producción.

Herramientas Adicionales para Desarrolladores

• Monitor de Estado del Servicio: Panel de disponibilidad de API en tiempo real
• Búsqueda de Códigos de Institución: Base de datos de referencia de instituciones financieras
• Guías de Integración: Tutoriales paso a paso en español
• Referencia de Códigos de Error: Explicaciones detalladas de todas las respuestas de error

Análisis Profundo del Stack Tecnológico

La API CoDi está construida con tecnologías modernas y probadas elegidas por su confiabilidad, rendimiento y capacidades de seguridad.

Tecnologías Backend

                

                  Stack Backend
                  Copy
                
                // Core Technologies
Runtime:    Node.js 18.x+
Framework:  Express.js
Language:   JavaScript (ES6+)
Database:   Supabase (PostgreSQL)
Testing:    Jest with coverage reporting
Process:    PM2 for production
Docs:       Swagger/OpenAPI 3.0

Stack de Seguridad

                

                  Tecnologías de Seguridad
                  Copy
                
                // Security Components
Authentication:     RSA certificates (2048-bit minimum)
API Keys:           128-character hexadecimal
Middleware:         Helmet.js, CORS, Rate Limiting
Validation:         Custom sanitization layer
Digital Signatures: All Banxico requests signed

Integraciones Clave

• API de Banxico: Endpoints oficiales del sistema de pagos CoDi
• Supabase: Base de datos, almacenamiento de claves API, registro de solicitudes/respuestas
• Generación de Códigos QR: Códigos QR de pago dinámicos
• Webhooks: Notificaciones de pago asíncronas

Desarrollo y DevOps

• Control de Versiones: Git/GitHub
• CI/CD: Flujo de despliegue con GitHub Actions
• Gestión de Entorno: dotenv para configuración
• Cumplimiento de Licencias: Verificación y reporte automatizado de licencias

Arquitectura de Base de Datos

La API usa Supabase (PostgreSQL) para persistencia de datos, con un esquema que soporta múltiples clientes, registro de auditoría completo y seguimiento de pagos.

Esquema de Base de Datos

La base de datos consiste en 5 tablas principales que trabajan juntas para gestionar clientes, claves API, transacciones de pago y registro completo de auditoría:

Características de Integridad de Datos

• Las restricciones de clave foránea aseguran la integridad referencial
• Las columnas de marca de tiempo rastrean creación y actualizaciones
• La segregación de entornos previene la mezcla de datos de prueba/producción
• Consultas indexadas para búsquedas rápidas de pagos

Análisis Profundo de Características de Seguridad

La seguridad es primordial al manejar transacciones financieras. La API CoDi implementa múltiples capas de seguridad para proteger datos sensibles de pago y asegurar el cumplimiento con regulaciones bancarias.

Autenticación de Firma Digital

Cada solicitud a Banxico está firmada digitalmente usando certificados RSA. Esto asegura que Banxico pueda verificar que la solicitud se originó de una instancia autorizada de la API CoDi y no ha sido alterada.

                

                  JavaScript - Generación de Firma Digital
                  Copy
                
                // Example of RSA signature generation
const crypto = require('crypto');
const fs = require('fs');

function generateDigitalSignature(payload, privateKeyPath) {
  // Load RSA private key
  const privateKey = fs.readFileSync(privateKeyPath, 'utf8');

  // Create signature using SHA256 with RSA
  const sign = crypto.createSign('SHA256');
  sign.update(JSON.stringify(payload));
  sign.end();

  // Generate signature in base64 format
  const signature = sign.sign(privateKey, 'base64');

  return signature;
}

Validación de Certificados

La API valida certificados RSA comparando números de serie y verificando la autenticidad del certificado antes de aceptar cualquier solicitud. Esto previene el acceso no autorizado incluso si alguien obtiene una clave API válida.

Lista Blanca de IPs y Control de Acceso

El sistema implementa lista blanca estricta de IPs a través de tres capas de seguridad para asegurar que solo clientes autorizados puedan acceder a la infraestructura de pagos:

• Capa de Firewall: El filtrado de IP a nivel de red bloquea tráfico no autorizado antes de que llegue a la aplicación
• Capa de API: La validación de IP a nivel de aplicación asegura que solo IPs de clientes registrados puedan hacer solicitudes a la API
• Capa Bancaria: Banxico requiere direcciones IP pre-registradas para todas las conexiones al sistema CoDi, proporcionando un punto de control de seguridad adicional

Esta arquitectura de restricción de IP multicapa asegura que incluso con credenciales válidas, el acceso solo sea posible desde ubicaciones de red aprobadas, reduciendo significativamente la superficie de ataque.

Gestión de Claves API

Las claves API son cadenas hexadecimales de 128 caracteres almacenadas de forma segura en Supabase. Cada clave está vinculada a un cliente específico y entorno (Beta o Producción), con límites de tasa y permisos individuales.

Sanitización de Solicitudes

Todas las solicitudes entrantes son sanitizadas para prevenir inyección SQL, ataques XSS y otras vulnerabilidades comunes. La validación de entrada asegura que solo datos con formato apropiado lleguen a la capa de integración con Banxico.

Limitación de Tasa

La API implementa limitación de tasa para prevenir abuso y asegurar asignación justa de recursos. El límite predeterminado es 200 solicitudes por ventana de 15 minutos por clave API.

Encabezados de Seguridad

Helmet.js agrega encabezados de seguridad a todas las respuestas, protegiendo contra vulnerabilidades web comunes como clickjacking, XSS y detección de tipo de contenido.

Referencia de Endpoints de API

La API CoDi expone 5 endpoints principales para gestionar pagos digitales. Todos los endpoints requieren autenticación de clave API a través del encabezado x-api-key.

Vista General de Endpoints

Endpoint	Método	Propósito
/v2/health	GET	Verificación de salud y estado del sistema
/v2/codi/qr	POST	Generar solicitud de pago con código QR
/v2/codi/push	POST	Enviar solicitud de pago por notificación push
/v2/codi/consulta	POST	Consultar estado de pago por folioCoDi
/v2/resultadoOperaciones	POST	Endpoint de webhook para callbacks de pago

Casos de Uso

La API CoDi es versátil y puede integrarse en una amplia variedad de aplicaciones empresariales. Aquí están los casos de uso más comunes:

1. Plataformas de Comercio Electrónico

Las tiendas en línea pueden integrar CoDi como opción de pago al momento del checkout, ofreciendo a los clientes una alternativa sin comisiones a las tarjetas de crédito.

• Integración con carrito de compras
• Flujos de confirmación de pedidos
• Actualizaciones automáticas de inventario al recibir el pago
• Recibos y facturas por correo electrónico

2. Sistemas de Punto de Venta

Las ubicaciones de comercio físico pueden usar CoDi para pagos en persona, mostrando códigos QR en el mostrador o enviando notificaciones push.

• Mostradores de pago en comercio minorista
• Escritorios de servicio y quioscos
• Terminales POS móviles
• Sistemas de pago para restaurantes

3. Proveedores de Servicios

Las empresas basadas en servicios pueden solicitar pagos de forma remota a través de notificaciones push, perfecto para facturación recurrente o servicios bajo demanda.

• Pagos de servicios públicos y facturas
• Servicios de suscripción
• Servicios profesionales (consultores, freelancers)
• Servicios de mantenimiento y reparación

4. Mercados

Las plataformas multi-vendedor pueden usar CoDi para manejar transacciones peer-to-peer entre compradores y vendedores.

• Plataformas de transacciones peer-to-peer
• Anuncios clasificados y listados
• Mercados freelance
• Plataformas basadas en comisiones

¿Te gustaría implementar CoDi para tu negocio? Contáctame y te ayudaré a integrarlo.

Código Abierto y Comunidad

La API CoDi es de código abierto bajo la licencia Apache 2.0, lo que significa que puedes usarla comercialmente, modificarla, distribuirla e incluso patentarla, con restricciones mínimas.

Beneficios de la Licencia Apache 2.0

• Uso Comercial: Usa la API en productos comerciales sin tarifas
• Modificación: Personaliza el código para ajustarse a tus necesidades específicas
• Distribución: Distribuye versiones modificadas o sin modificar
• Concesión de Patente: Protección contra demandas de patentes
• Sin Garantía: Proporcionado "tal cual" sin responsabilidad

Contribuir al Proyecto

¡Las contribuciones son bienvenidas! Ya sea que estés arreglando errores, agregando funciones, mejorando la documentación o reportando problemas, tu ayuda hace que el proyecto sea mejor para todos.

Cómo Contribuir

1. Haz fork del repositorio en GitHub
2. Crea una rama de funcionalidad (git checkout -b feature/nueva-funcionalidad))
3. Haz commit de tus cambios (git commit -m 'Agregar nueva funcionalidad'))
4. Haz push a la rama (git push origin feature/nueva-funcionalidad))
5. Abre un Pull Request

Recursos de la Comunidad

• GitHub Issues: Reporta errores y solicita funciones
• GitHub Discussions: Haz preguntas y comparte ideas
• Documentación: Guías completas y referencia de API
• Ejemplos de Código: Ejemplos de integración del mundo real

Enlaces del Proyecto y Recursos

Servicios en Vivo

• Endpoint de API - URL base de la API de producción
• Sitio de Documentación - Guías completas y tutoriales
• Playground de API - Entorno de pruebas interactivo
• Documentación Swagger - Referencia completa de la API

Código y Comunidad

• Repositorio de GitHub - Código fuente y README
• Issues - Reportes de errores y solicitudes de funciones
• Discusiones - Preguntas de la comunidad e ideas

Recursos Externos

• CoDi Oficial de Banxico - Información de CoDi del Banco de México