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

# MCH-024: CoDi y SPEI

## Metadata
- **Codigo:** MCH-024
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 15-16

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

```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-07