# MGN-016: Integraciones de Pagos y POS

## Descripción del Módulo

El módulo de Integraciones de Pagos y POS permite a los tenants conectar terminales de pago y procesadores para cobrar a sus propios clientes. Esto incluye integraciones con MercadoPago, Clip, Stripe Terminal, y otros proveedores de pagos en punto de venta.

**IMPORTANTE:** Este módulo es diferente a MGN-015 (Billing):
- **MGN-015:** Cobra a los tenants por usar la plataforma SaaS
- **MGN-016:** Permite a los tenants cobrar a sus clientes finales

## Requerimientos Funcionales

| ID | Nombre | Prioridad | Story Points | Estado |
|----|--------|-----------|--------------|--------|
| [RF-MGN-016-001](./RF-MGN-016-001-integracion-mercadopago.md) | Integración MercadoPago | P1 | 13 | Definido |
| [RF-MGN-016-002](./RF-MGN-016-002-integracion-clip.md) | Integración Clip | P1 | 13 | Definido |
| [RF-MGN-016-003](./RF-MGN-016-003-integracion-stripe-terminal.md) | Integración Stripe Terminal | P2 | 8 | Definido |
| [RF-MGN-016-004](./RF-MGN-016-004-gestion-terminales.md) | Gestión de Terminales | P1 | 8 | Definido |
| [RF-MGN-016-005](./RF-MGN-016-005-conciliacion-pagos.md) | Conciliación de Pagos | P1 | 13 | Definido |
| [RF-MGN-016-006](./RF-MGN-016-006-reportes-transacciones.md) | Reportes de Transacciones | P2 | 5 | Definido |

**Total Story Points:** 60

## Arquitectura de Integraciones

```
┌──────────────────────────────────────────────────────────────────┐
│                         TENANT (Cliente SaaS)                     │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │ MercadoPago │    │    Clip     │    │   Stripe    │          │
│  │  Credentials│    │  Credentials│    │  Credentials│          │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘          │
│         │                  │                   │                  │
└─────────┼──────────────────┼───────────────────┼──────────────────┘
          │                  │                   │
          ▼                  ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   MercadoPago   │  │      Clip       │  │  Stripe API     │
│      API        │  │      API        │  │    Terminal     │
└─────────────────┘  └─────────────────┘  └─────────────────┘
```

## Dependencias

### Dependencias Internas
- **MGN-003 (Catalogs):** Métodos de pago, monedas, contactos
- **MGN-004 (Financial):** Registro contable de pagos recibidos (auto-asientos)
- **MGN-007 (Sales):** Pagos de órdenes de venta (actualizar estado)
- **MGN-014 (Mensajería):** Notificaciones de transacciones y auditoría
- **MGN-015 (Billing):** Feature flags (mercadopago_enabled, clip_enabled)

### Dependencias Externas
- MercadoPago API (OAuth2, Webhooks)
- Clip API (API Keys, Webhooks)
- Stripe API (Connect, Terminal)

### Integraciones Requeridas
- **MGN-007:** Webhook `payment.approved` debe actualizar `sales.orders.payment_status`
- **MGN-004:** Transacciones confirmadas deben generar asientos contables automáticos

## Actores del Módulo

| Actor | Descripción | RFs Relacionados |
|-------|-------------|------------------|
| Tenant Admin | Configura integraciones | RF-001, RF-002, RF-003, RF-004 |
| Cajero/Vendedor | Procesa pagos | RF-001, RF-002, RF-003 |
| Contador | Concilia transacciones | RF-005, RF-006 |
| Sistema | Webhooks y sincronización | Todos |

## Entidades Principales

```sql
-- Schema: integrations
integrations.payment_providers       -- Proveedores configurados por tenant
integrations.payment_credentials     -- Credenciales encriptadas (OAuth tokens, API keys)
integrations.payment_terminals       -- Terminales físicas registradas
integrations.payment_transactions    -- Transacciones procesadas
integrations.webhook_logs            -- Logs de webhooks recibidos
integrations.reconciliation_batches  -- Lotes de conciliación
```

## Proveedores Soportados

### MercadoPago (México, LATAM)
- **Métodos:** Tarjeta, OXXO, SPEI, Mercado Crédito
- **Terminales:** Point Smart, Point Pro
- **Comisiones:** 3.49% + IVA (tarjeta presencial)

### Clip (México)
- **Métodos:** Tarjeta (crédito/débito)
- **Terminales:** Clip Plus, Clip Pro
- **Comisiones:** 3.6% + IVA

### Stripe Terminal (Global)
- **Métodos:** Tarjeta (crédito/débito)
- **Terminales:** BBPOS WisePOS E, Verifone P400
- **Comisiones:** 2.9% + $0.30 USD

## Flujo General de Pago

```
┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│ Vendedor│────▶│   ERP   │────▶│ Gateway │────▶│  Banco  │
│  (POS)  │     │ (crear  │     │(procesar│     │(aprobar)│
└─────────┘     │ intent) │     │  pago)  │     └────┬────┘
                └─────────┘     └─────────┘          │
                      ▲                              │
                      │         ┌─────────┐         │
                      └─────────│ Webhook │◀────────┘
                                │(confirmar│
                                └─────────┘
```

## Seguridad

1. **Credenciales:** Encriptadas con AES-256, nunca en logs
2. **OAuth:** Refresh tokens con rotación automática
3. **Webhooks:** Validación de firma (HMAC)
4. **PCI-DSS:** Datos de tarjeta nunca tocan nuestros servidores
5. **Auditoría:** Todas las transacciones logueadas

## Notas de Implementación

1. **Multi-proveedor:** Un tenant puede tener múltiples proveedores activos
2. **Failover:** Si un proveedor falla, ofrecer alternativa
3. **Offline:** Soportar modo offline para terminales físicas
4. **Notificaciones:** Alertar sobre transacciones fallidas
5. **Reconciliación:** Job diario para conciliar con extractos

## Feature Flags

```json
{
  "mercadopago_enabled": true,
  "clip_enabled": true,
  "stripe_terminal_enabled": false,
  "offline_mode": true,
  "auto_reconciliation": true
}
```