michangarrito/docs/01-epicas/MCH-024-codi-spei.md

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-024	Epic	MCH-024: CoDi y SPEI	MCH-024	Parcial	Mock	Implementacion mock - Sin integracion real con Banxico/STP	6	P2	2026-01-10	2026-01-17	4.0.1	21	blocks depends_on

MCH-024: CoDi y SPEI

Metadata

• Codigo: MCH-024
• Fase: 6 - Crecimiento
• Prioridad: P2
• Estado: Parcial (Mock)
• Estado Real: Implementacion mock - Genera QR y CLABE simulados
• Story Points: 21
• Fecha completado: 2026-01-10
• Sprint Asignado: Sprint 5 (Integraciones Reales)
• Requiere: Contrato con STP/Arcus, Certificacion Banxico
• 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

Historias de Usuario

MCH-US-230: Generacion de QR CoDi

Story Points: 5

Como operador de punto de venta Quiero generar un codigo QR CoDi con el monto de la venta Para que el cliente pueda pagar instantaneamente sin comisiones desde su app bancaria

Criterios de Aceptacion

• [CA-230-1] El sistema genera un QR CoDi valido con el monto exacto de la venta
• [CA-230-2] El QR incluye la referencia unica de la transaccion
• [CA-230-3] El QR tiene una vigencia configurable (default 5 minutos)
• [CA-230-4] El QR es compatible con las apps bancarias que soportan CoDi
• [CA-230-5] Se muestra mensaje de error claro si la generacion falla

Tareas

ID	Tarea	Estimacion
MCH-TT-230-01	Implementar codi.service.ts con metodo generateQR	4h
MCH-TT-230-02	Crear endpoint POST /codi/generate-qr	2h
MCH-TT-230-03	Integrar con SDK/API del proveedor CoDi	4h
MCH-TT-230-04	Crear tabla codi_transactions en BD	2h
MCH-TT-230-05	Agregar tests unitarios para generacion QR	2h

---

MCH-US-231: Confirmacion de Pago CoDi

Story Points: 5

Como sistema de MiChangarrito Quiero recibir y procesar el webhook de confirmacion de Banxico Para actualizar automaticamente el estado de la venta cuando el pago sea exitoso

Criterios de Aceptacion

• [CA-231-1] El webhook recibe notificaciones de Banxico en tiempo real
• [CA-231-2] El sistema valida la autenticidad del webhook (firma/token)
• [CA-231-3] La venta se marca como pagada automaticamente al confirmar
• [CA-231-4] Se envia notificacion push al POS cuando el pago se confirma
• [CA-231-5] Se registra timestamp de confirmacion en codi_transactions
• [CA-231-6] Manejo de reintentos para webhooks duplicados (idempotencia)

Tareas

ID	Tarea	Estimacion
MCH-TT-231-01	Implementar endpoint POST /codi/webhook	3h
MCH-TT-231-02	Validar firma/autenticacion del webhook	2h
MCH-TT-231-03	Actualizar estado de venta en BD	2h
MCH-TT-231-04	Implementar notificacion push al POS	3h
MCH-TT-231-05	Agregar manejo de idempotencia	2h
MCH-TT-231-06	Tests de integracion para webhook	2h

---

MCH-US-232: CLABE Virtual por Tenant

Story Points: 4

Como tenant de MiChangarrito Quiero tener una CLABE virtual unica asignada a mi negocio Para recibir pagos SPEI directamente y que se concilien automaticamente

Criterios de Aceptacion

• [CA-232-1] Se genera CLABE virtual unica al activar SPEI para el tenant
• [CA-232-2] La CLABE se almacena en tabla virtual_accounts
• [CA-232-3] El tenant puede ver su CLABE en el dashboard
• [CA-232-4] La CLABE incluye nombre del beneficiario correcto
• [CA-232-5] Se puede copiar la CLABE con un click

Tareas

ID	Tarea	Estimacion
MCH-TT-232-01	Crear tabla virtual_accounts en BD	1h
MCH-TT-232-02	Integrar con proveedor (STP/Arcus) para generar CLABE	4h
MCH-TT-232-03	Implementar endpoint GET /spei/clabe	2h
MCH-TT-232-04	Crear componente CLABEDisplay en frontend	2h
MCH-TT-232-05	Tests de integracion con proveedor	2h

---

MCH-US-233: Recepcion y Conciliacion de SPEI

Story Points: 4

Como sistema de MiChangarrito Quiero recibir notificaciones de pagos SPEI entrantes Para conciliar automaticamente los pagos con las ventas pendientes

Criterios de Aceptacion

• [CA-233-1] El webhook recibe notificaciones de SPEI entrantes
• [CA-233-2] Se registra la transaccion en spei_transactions
• [CA-233-3] El sistema intenta conciliar automaticamente con ventas pendientes
• [CA-233-4] Si no hay match, se registra como pago no conciliado
• [CA-233-5] Se notifica al tenant cuando recibe un pago SPEI
• [CA-233-6] Se puede ver historial de transacciones SPEI recibidas

Tareas

ID	Tarea	Estimacion
MCH-TT-233-01	Crear tabla spei_transactions en BD	1h
MCH-TT-233-02	Implementar endpoint POST /spei/webhook	3h
MCH-TT-233-03	Implementar logica de conciliacion automatica	4h
MCH-TT-233-04	Implementar endpoint GET /spei/transactions	2h
MCH-TT-233-05	Agregar notificacion al tenant	2h
MCH-TT-233-06	Tests de conciliacion	2h

---

MCH-US-234: UI de Pago CoDi

Story Points: 3

Como operador de punto de venta Quiero una pantalla clara que muestre el QR CoDi con timer Para guiar al cliente durante el proceso de pago y saber cuando se confirma

Criterios de Aceptacion

• [CA-234-1] Boton "Pagar con CoDi" visible en opciones de pago
• [CA-234-2] QR se muestra grande y claro con monto visible
• [CA-234-3] Timer de cuenta regresiva muestra tiempo restante
• [CA-234-4] Instrucciones claras para el cliente
• [CA-234-5] Indicador visual cuando el pago esta siendo procesado
• [CA-234-6] Confirmacion visual cuando el pago es exitoso
• [CA-234-7] Boton para regenerar QR si expira

Tareas

ID	Tarea	Estimacion
MCH-TT-234-01	Crear componente CoDiPaymentOption	2h
MCH-TT-234-02	Crear componente QRCodeDisplay con timer	3h
MCH-TT-234-03	Integrar con WebSocket para confirmacion en tiempo real	3h
MCH-TT-234-04	Agregar animaciones de estado (esperando, confirmado)	2h
MCH-TT-234-05	Tests de componentes UI	2h

---

Resumen de Historias de Usuario

ID	Historia	Story Points	Prioridad
MCH-US-230	Generacion de QR CoDi	5	Alta
MCH-US-231	Confirmacion de Pago CoDi	5	Alta
MCH-US-232	CLABE Virtual por Tenant	4	Media
MCH-US-233	Recepcion y Conciliacion de SPEI	4	Media
MCH-US-234	UI de Pago CoDi	3	Alta
Total		21

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-17