# MCH-005: Integraciones de Pago

## Metadata
- **Codigo:** MCH-005
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **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

---

**Ultima actualizacion:** 2026-01-07