---
id: EPIC-MCH-005
type: Epic
title: "MCH-005: Integraciones de Pago"
code: MCH-005
status: Completado
phase: 1
priority: P0
story_points: 13
created_at: 2026-01-06
updated_at: 2026-01-17
simco_version: "4.0.1"
dependencies:
  blocks: ["MCH-018", "MCH-020"]
  depends_on: ["MCH-001", "MCH-002", "MCH-004"]
---

# MCH-005: Integraciones de Pago

## Metadata
- **Codigo:** MCH-005
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **Story Points:** 13
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07

## Descripcion

Integracion con proveedores de pago populares en Mexico para aceptar pagos con tarjeta: Mercado Pago (lector bluetooth), Clip, y efectivo. Soporte para suscripciones via Stripe.

## Objetivos

1. Integracion Mercado Pago Point
2. Integracion Clip
3. Registro de pagos en efectivo
4. Stripe para suscripciones
5. Conciliacion de pagos

## Alcance

### Incluido
- Mercado Pago Point (lector bluetooth)
- Clip (terminal)
- Efectivo (registro manual)
- Stripe (suscripciones y OXXO)
- Webhooks para confirmacion

### Excluido
- CoDi/SPEI - MCH-024
- Pagos QR propios - fase posterior
- Terminales bancarias tradicionales

## Proveedores

### Mercado Pago
- **Uso:** Pagos con tarjeta en tienda
- **Hardware:** Point Bluetooth
- **Comision:** ~3.5%
- **Integracion:** SDK + Webhooks

### Clip
- **Uso:** Pagos con tarjeta en tienda
- **Hardware:** Terminal Clip
- **Comision:** ~3.6%
- **Integracion:** SDK + Webhooks

### Stripe
- **Uso:** Suscripciones, pagos en linea, OXXO
- **Comision:** ~3.6% + $3 MXN
- **Integracion:** API + Webhooks

### Efectivo
- **Uso:** Pagos en efectivo
- **Registro:** Manual en POS
- **Control:** Corte de caja

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /payments/intent | Crear intencion de pago |
| POST | /payments/confirm | Confirmar pago |
| GET | /payments/:id | Obtener pago |
| POST | /payments/webhook | Webhook de proveedores |
| GET | /payments/methods | Metodos disponibles |

## Flujos de Pago

### Pago con Tarjeta (MercadoPago/Clip)
```
1. Venta creada en POS
2. Empleado selecciona "Tarjeta"
3. Se envia monto a terminal
4. Cliente pasa tarjeta
5. Webhook confirma pago
6. Venta marcada como pagada
7. Ticket generado
```

### Pago en Efectivo
```
1. Venta creada en POS
2. Empleado selecciona "Efectivo"
3. Ingresa monto recibido
4. Sistema calcula cambio
5. Venta registrada
6. Actualiza caja
```

### Pago OXXO (Stripe)
```
1. Cliente solicita pago en OXXO
2. Sistema genera referencia Stripe
3. Se muestra codigo de barras
4. Cliente paga en OXXO
5. Webhook confirma (24-48h)
6. Pedido/suscripcion activada
```

## Modelo de Datos

### Tablas

**payments** (en sales schema)
- id, sale_id, provider, amount
- reference, status, metadata
- created_at, confirmed_at

**payment_methods** (por tenant)
- id, tenant_id, provider, credentials
- settings, active

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| payments.module | Completado | `modules/payments/` |
| stripe.provider | Completado | `providers/stripe.provider.ts` |
| mercadopago.provider | Completado | `providers/mercadopago.provider.ts` |
| PaymentModal | Completado | `components/pos/PaymentModal.tsx` |

## Dependencias

### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth)
- MCH-004 (POS)

### Bloquea a
- MCH-018 (Suscripciones)
- MCH-020 (Pagos online)

## Criterios de Aceptacion

- [x] Mercado Pago procesa pagos
- [x] Webhooks se reciben correctamente
- [x] Efectivo registra correctamente
- [x] Stripe funciona para suscripciones
- [x] Conciliacion de pagos funciona

## Configuracion por Tenant

```typescript
// tenant_integrations
{
  provider: 'mercadopago',
  credentials: {
    access_token: 'encrypted...',
    public_key: '...'
  },
  settings: {
    point_device_id: '...'
  }
}
```

## Seguridad

- Credenciales encriptadas en BD
- Webhooks verificados con firma
- Logs de todas las transacciones
- PCI compliance delegado a proveedores

---

## Historias de Usuario

### MCH-US-040: Integracion Mercado Pago Point

**Como** empleado de tienda
**Quiero** procesar pagos con tarjeta usando el lector Mercado Pago Point
**Para** ofrecer una opcion de pago rapida y segura a los clientes

**Story Points:** 3

**Criterios de Aceptacion:**
- [CA-040-1] ✅ Configuracion de credenciales Mercado Pago por tenant
- [CA-040-2] ✅ Conexion bluetooth con dispositivo Point establecida
- [CA-040-3] ✅ Monto enviado correctamente a terminal
- [CA-040-4] ✅ Webhook de confirmacion procesado en <5 segundos
- [CA-040-5] ✅ Venta marcada como pagada automaticamente

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-040-01 | Configurar SDK Mercado Pago | Backend | Completado |
| MCH-TT-040-02 | Implementar MercadoPagoProvider | Backend | Completado |
| MCH-TT-040-03 | Endpoint webhook MercadoPago | Backend | Completado |
| MCH-TT-040-04 | UI seleccion Mercado Pago en POS | Frontend | Completado |
| MCH-TT-040-05 | Tests de integracion | Test | Completado |

---

### MCH-US-041: Integracion Clip

**Como** empleado de tienda
**Quiero** procesar pagos con tarjeta usando terminal Clip
**Para** tener una alternativa de pago con tarjeta

**Story Points:** 3

**Criterios de Aceptacion:**
- [CA-041-1] ✅ Configuracion de credenciales Clip por tenant
- [CA-041-2] ✅ Envio de monto a terminal Clip
- [CA-041-3] ✅ Recepcion de webhook de confirmacion
- [CA-041-4] ✅ Manejo de errores y rechazos de tarjeta
- [CA-041-5] ✅ Registro de transaccion en base de datos

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-041-01 | Implementar ClipProvider | Backend | Completado |
| MCH-TT-041-02 | Endpoint webhook Clip | Backend | Completado |
| MCH-TT-041-03 | UI seleccion Clip en POS | Frontend | Completado |
| MCH-TT-041-04 | Manejo de errores de pago | Backend | Completado |

---

### MCH-US-042: Registro de Pagos en Efectivo

**Como** empleado de tienda
**Quiero** registrar pagos en efectivo con calculo automatico de cambio
**Para** mantener control preciso de la caja

**Story Points:** 2

**Criterios de Aceptacion:**
- [CA-042-1] ✅ Seleccion de metodo de pago "Efectivo" en POS
- [CA-042-2] ✅ Input para monto recibido del cliente
- [CA-042-3] ✅ Calculo automatico de cambio a devolver
- [CA-042-4] ✅ Actualizacion de saldo en caja
- [CA-042-5] ✅ Venta registrada con metodo efectivo

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-042-01 | Logica de calculo de cambio | Backend | Completado |
| MCH-TT-042-02 | UI pago efectivo en PaymentModal | Frontend | Completado |
| MCH-TT-042-03 | Integracion con corte de caja | Backend | Completado |

---

### MCH-US-043: Stripe para Suscripciones y OXXO

**Como** sistema
**Quiero** procesar pagos de suscripciones y OXXO via Stripe
**Para** habilitar cobros recurrentes y pago en tiendas de conveniencia

**Story Points:** 5

**Criterios de Aceptacion:**
- [CA-043-1] ✅ Configuracion de Stripe API keys por ambiente
- [CA-043-2] ✅ Creacion de intenciones de pago (PaymentIntent)
- [CA-043-3] ✅ Generacion de referencias OXXO con codigo de barras
- [CA-043-4] ✅ Procesamiento de webhooks Stripe (payment_intent.succeeded)
- [CA-043-5] ✅ Soporte para pagos recurrentes de suscripciones
- [CA-043-6] ✅ Confirmacion de pago OXXO en 24-48h via webhook

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-043-01 | Implementar StripeProvider | Backend | Completado |
| MCH-TT-043-02 | Endpoint crear PaymentIntent | Backend | Completado |
| MCH-TT-043-03 | Endpoint generar referencia OXXO | Backend | Completado |
| MCH-TT-043-04 | Webhook Stripe multiproposito | Backend | Completado |
| MCH-TT-043-05 | Integracion con modulo suscripciones | Backend | Completado |
| MCH-TT-043-06 | Tests unitarios Stripe | Test | Completado |

---

## Resumen de Story Points

| Historia | SP | Estado |
|----------|-----|--------|
| MCH-US-040: Integracion Mercado Pago Point | 3 | Completado |
| MCH-US-041: Integracion Clip | 3 | Completado |
| MCH-US-042: Registro de Pagos en Efectivo | 2 | Completado |
| MCH-US-043: Stripe para Suscripciones y OXXO | 5 | Completado |
| **TOTAL** | **13** | **100%** |

---

**Ultima actualizacion:** 2026-01-17