michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-024-codi-spei.md

MCH-024: CoDi y SPEI

Metadata

• Codigo: MCH-024
• Fase: 6 - Crecimiento
• Prioridad: P2
• Estado: Completado (Base)
• Fecha completado: 2026-01-10
• Nota: Requiere integracion con proveedor (STP/Arcus/Conekta)

Descripcion

Integracion con CoDi (Cobro Digital) de Banxico y SPEI para pagos instantaneos sin comision: generacion de QR de cobro, CLABE virtual por negocio, y confirmacion automatica.

Objetivos

1. Generacion de QR CoDi
2. CLABE virtual por tenant
3. Confirmacion automatica de pagos
4. Sin comisiones
5. Conciliacion automatica

Alcance

Incluido

• QR CoDi para cobro
• CLABE virtual (via proveedor)
• Webhook de confirmacion
• Registro de pagos en BD
• Notificacion al recibir pago

Excluido

• Transferencias salientes
• Pagos programados
• Domiciliacion

CoDi - Cobro Digital

Que es CoDi

• Sistema de Banxico
• Pagos via QR desde app bancaria
• Sin comisiones
• Confirmacion en segundos
• Opera 24/7

Flujo de Pago CoDi

1. Cliente quiere pagar
2. POS genera QR CoDi con monto
3. Cliente escanea con app de su banco
4. Cliente confirma pago
5. Dinero se transfiere instantaneamente
6. Webhook notifica a MiChangarrito
7. Venta marcada como pagada

SPEI con CLABE Virtual

Como Funciona

1. Tenant se registra
2. Se genera CLABE virtual unica
3. Clientes pueden transferir a esa CLABE
4. Pagos se concilian automaticamente
5. Ideal para pagos grandes o B2B

Proveedores de CLABE Virtual

• STP (Sistema de Transferencias y Pagos)
• Arcus
• Conekta
• Openpay

Modelo de Datos

Tablas Adicionales

codi_transactions

• id, tenant_id, sale_id
• qr_data, amount, reference
• status, confirmed_at

virtual_accounts

• id, tenant_id, provider
• clabe, status, created_at

spei_transactions

• id, tenant_id, virtual_account_id
• amount, sender_clabe, sender_name
• reference, received_at

Endpoints API

Metodo	Endpoint	Descripcion
POST	/codi/generate-qr	Generar QR de cobro
GET	/codi/status/:id	Estado de transaccion
POST	/codi/webhook	Webhook de confirmacion
GET	/spei/clabe	Obtener CLABE virtual
POST	/spei/webhook	Webhook de SPEI
GET	/spei/transactions	Transacciones recibidas

Flujo Tecnico CoDi

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│     POS     │────▶│  Generate   │────▶│  QR Image   │
│             │     │    QR       │     │  Displayed  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                                        ┌──────▼──────┐
                                        │  Customer   │
                                        │  Scans QR   │
                                        └──────┬──────┘
                                               │
                                        ┌──────▼──────┐
                                        │  Bank App   │
                                        │  Confirms   │
                                        └──────┬──────┘
                                               │
┌─────────────┐     ┌─────────────┐     ┌──────▼──────┐
│   Update    │◀────│   Webhook   │◀────│   Banxico   │
│    Sale     │     │   Handler   │     │    CoDi     │
└─────────────┘     └─────────────┘     └─────────────┘

UI Components

CoDiPaymentOption

• Boton "Pagar con CoDi"
• Genera y muestra QR
• Timer de expiracion (5 min)
• Indicador de esperando pago

QRCodeDisplay

• QR grande y claro
• Monto visible
• Instrucciones
• Boton "Ya pague"

CLABEDisplay

• CLABE formateada
• Boton copiar
• Nombre del beneficiario

Entregables

Entregable	Estado	Archivo
codi.service	Pendiente	services/codi.service.ts
spei.service	Pendiente	services/spei.service.ts
CoDi QR UI	Pendiente	components/payments/CoDiQR.tsx
Virtual account setup	Pendiente	Integracion proveedor

Dependencias

Depende de

• MCH-004 (POS)
• MCH-005 (Payments base)
• Cuenta bancaria del negocio

Bloquea a

• Ninguno

Criterios de Aceptacion

• QR CoDi se genera correctamente
• Pago CoDi se confirma automaticamente
• CLABE virtual se asigna
• SPEI se recibe y concilia
• Sin comisiones extra

Limitaciones

Aspecto	Limitacion
Monto minimo	$1 MXN
Monto maximo	$8,000 MXN (CoDi)
Horario	24/7
Bancos	20+ bancos soportan CoDi

Configuracion por Tenant

{
  codi: {
    enabled: true,
    provider: 'banxico', // o agregador
    merchant_id: '...',
    qr_expiry_minutes: 5
  },
  spei: {
    enabled: true,
    provider: 'stp',
    clabe: '646180123456789012',
    auto_reconcile: true
  }
}

Beneficios vs Tarjeta

Aspecto	Tarjeta	CoDi/SPEI
Comision	3-4%	0%
Confirmacion	Inmediata	Inmediata
Contracargos	Posible	No
Requiere terminal	Si	No

---

Ultima actualizacion: 2026-01-07