---
id: EPIC-MCH-024
type: Epic
title: "MCH-024: CoDi y SPEI"
code: MCH-024
status: Completado
status_real: "Mock"
status_nota: "Implementacion mock - Sin integracion real con Banxico/STP"
phase: 6
priority: P2
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 21
dependencies:
  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

```typescript
{
  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