michangarrito/docs/02-integraciones/INT-006-codi-banxico.md

id	type	title	provider	status	integration_type	created_at	updated_at	simco_version	tags
INT-006	Integration	Pagos CoDi/SPEI	Banxico/STP	Mock	Pagos QR instantáneos	2026-01-10	2026-01-10	3.8.0	pagos codi spei qr banxico transferencias

INT-006: Pagos CoDi/SPEI

Metadata

Campo	Valor
Codigo	INT-006
Proveedor	Banxico/STP
Tipo	Pagos QR instantáneos
Estado	Mock (en desarrollo)
Multi-tenant	Si
Fecha planeada	2026-Q1
Owner	Backend Team

---

1. Descripcion

Integración con el sistema de Cobro Digital (CoDi) de Banxico y transferencias SPEI a través de STP (Sistema de Transferencias y Pagos). Permite a los changarros recibir pagos instantáneos mediante códigos QR, sin comisiones por transacción. CoDi opera sobre la infraestructura de SPEI, garantizando transferencias en tiempo real 24/7.

Casos de uso principales:

• Generación de códigos QR para cobro instantáneo
• Recepción de pagos SPEI sin comisión
• Notificación en tiempo real de pagos recibidos
• Conciliación automática de transacciones
• Generación de comprobantes electrónicos de pago

---

2. Credenciales Requeridas

Variables de Entorno

Variable	Descripcion	Tipo	Obligatorio
STP_EMPRESA	Identificador de empresa en STP	string	SI
STP_CLAVE_PRIVADA	Llave privada para firmar mensajes	string	SI
STP_CERTIFICADO	Certificado digital .cer	string	SI
STP_CUENTA_CLABE	CLABE de la cuenta receptora	string	SI
STP_WEBHOOK_URL	URL para recibir notificaciones	string	SI
CODI_MERCHANT_ID	ID de comercio registrado en CoDi	string	SI
CODI_API_KEY	Llave de API de CoDi	string	SI

Ejemplo de .env

# Pagos CoDi/SPEI
STP_EMPRESA=MICHANGARRITO
STP_CLAVE_PRIVADA=/path/to/private_key.pem
STP_CERTIFICADO=/path/to/certificate.cer
STP_CUENTA_CLABE=646180157000000001
STP_WEBHOOK_URL=https://api.michangarrito.mx/webhooks/stp
CODI_MERCHANT_ID=codi_mer_xxxxxxxx
CODI_API_KEY=codi_key_xxxxxxxx

---

3. Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                      MiChangarrito                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │   Frontend   │───▶│  API Server  │───▶│  CoDiService     │  │
│  │   (POS/App)  │    │              │    │                  │  │
│  └──────────────┘    └──────────────┘    └────────┬─────────┘  │
└────────────────────────────────────────────────────┼────────────┘
                                                     │
                           ┌─────────────────────────┼─────────────┐
                           │                         ▼             │
                           │  ┌──────────────────────────────┐    │
                           │  │         STP Gateway          │    │
                           │  └──────────────┬───────────────┘    │
                           │                 │                     │
                           │                 ▼                     │
                           │  ┌──────────────────────────────┐    │
                           │  │     Banxico SPEI / CoDi      │    │
                           │  │   (Red Interbancaria MX)     │    │
                           │  └──────────────────────────────┘    │
                           │           Sistema Financiero         │
                           └───────────────────────────────────────┘

Flujo de Pago CoDi

1. Comercio genera solicitud de cobro con monto
2. Sistema genera código QR con datos CoDi
3. Cliente escanea QR con app bancaria
4. Banco del cliente procesa transferencia SPEI
5. STP notifica la recepción del pago
6. Sistema actualiza estado de la venta en tiempo real

---

4. Endpoints

Endpoints Consumidos (STP/CoDi API)

Método	Endpoint	Descripción
POST	/v1/codi/cobros	Generar solicitud de cobro CoDi
GET	/v1/codi/cobros/{id}	Consultar estado de cobro
POST	/v1/spei/ordenPago	Registrar orden de pago SPEI
GET	/v1/spei/consultaOrden/{id}	Consultar orden SPEI
GET	/v1/cuentas/{clabe}/movimientos	Consultar movimientos

Endpoints Expuestos (MiChangarrito)

Método	Endpoint	Descripción
POST	/api/v1/payments/codi/generate	Generar QR de cobro
GET	/api/v1/payments/codi/{id}/status	Consultar estado
GET	/api/v1/payments/codi/{id}/qr	Obtener imagen QR
POST	/api/v1/webhooks/stp	Recibir notificaciones STP
GET	/api/v1/payments/spei/movements	Listar movimientos

---

5. Notas de Implementacion

• CoDi no cobra comisiones por transacción (beneficio vs tarjetas)
• Las transferencias SPEI son irreversibles una vez confirmadas
• Implementar timeout de 5 minutos para códigos QR
• Validar firma digital en todas las notificaciones de STP
• El registro como participante CoDi requiere trámite con Banxico
• Generar referencia única por transacción para conciliación
• Los QR deben cumplir con el estándar EMVCo para CoDi
• Horario de operación SPEI: 24/7, pero cortes contables a las 17:30
• Considerar implementar caché de CLABEs validadas
• Manejar reintentos en caso de falla de comunicación con STP