# EPICA: EPIC-MGN-017 - Payments POS

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-017 |
| **Nombre** | Payments POS (MercadoPago, Clip) |
| **Modulo** | payments |
| **Fase** | Fase 4 - SaaS Platform |
| **Prioridad** | P3 |
| **Estado** | Backlog |
| **Story Points** | 34 |
| **Sprint(s)** | Sprint 21-23 |

---

## Descripcion

Sistema de integracion con terminales de pago (MercadoPago y Clip) para procesar transacciones en punto de venta. Incluye registro de terminales por ubicacion, procesamiento de transacciones con tarjeta, reembolsos parciales/totales, webhooks para notificaciones y conciliacion automatica con generacion de asientos contables.

---

## Objetivo de Negocio

Proveer integracion de pagos que:
- Procese pagos fisicos y digitales en punto de venta
- Soporte multiples proveedores (MercadoPago, Clip)
- Automatice conciliacion con contabilidad
- Reduzca errores de captura manual
- Genere asientos contables automaticos
- Maneje comisiones de cada proveedor

---

## Stakeholders

| Rol | Nombre/Equipo | Responsabilidad |
|-----|---------------|-----------------|
| Product Owner | Equipo Producto | Definicion de proveedores y flujos |
| Tech Lead | Equipo Backend | Arquitectura de integraciones |
| Contador | Finanzas | Definicion de asientos contables |
| Cajeros | Operaciones | Uso diario, feedback UX |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN017-001 | Como admin, quiero registrar terminales de pago para identificar dispositivos | P0 | 3 | Backlog |
| US-MGN017-002 | Como admin, quiero configurar credenciales de MercadoPago (OAuth) | P0 | 5 | Backlog |
| US-MGN017-003 | Como admin, quiero configurar credenciales de Clip (API Keys) | P0 | 3 | Backlog |
| US-MGN017-004 | Como cajero, quiero procesar un pago con tarjeta para cobrar a cliente | P0 | 8 | Backlog |
| US-MGN017-005 | Como cajero, quiero procesar un reembolso para devolver a cliente | P0 | 5 | Backlog |
| US-MGN017-006 | Como sistema, quiero recibir webhooks de pagos para actualizar estados | P0 | 5 | Backlog |
| US-MGN017-007 | Como contador, quiero conciliar transacciones con extractos bancarios | P1 | 5 | Backlog |

**Total Story Points:** 34 SP

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Multi-provider: MercadoPago (OAuth) y Clip (API Keys)
- [ ] Registro de terminales por ubicacion/almacen
- [ ] Procesamiento de pagos con tarjeta (credito, debito)
- [ ] Reembolsos parciales y totales
- [ ] Webhooks para notificaciones de estado de pago
- [ ] Conciliacion de transacciones con extractos bancarios
- [ ] Asientos contables automaticos (Bancos, Comisiones, Ventas)
- [ ] Manejo de comisiones por provider

**No Funcionales:**
- [ ] Timeout de transacciones < 30s
- [ ] Retry automatico (3 intentos) en fallos de red
- [ ] Logs detallados para debugging y auditoria
- [ ] PCI DSS compliance (no almacenar datos de tarjeta)

**Tecnicos:**
- [ ] Cobertura de tests > 80%
- [ ] Documentacion de APIs de proveedores
- [ ] Manejo de errores estandarizado

---

## Integraciones

### MercadoPago
- **Autenticacion:** OAuth 2.0
- **Webhooks:** Para notificaciones de estado
- **APIs:** Payments, Refunds, Terminals, Device Management
- **Comision:** ~3.49% + IVA

### Clip
- **Autenticacion:** API Keys
- **Estado:** Polling (no tiene webhooks nativos)
- **APIs:** Transactions, Refunds, Terminals
- **Comision:** ~3.6% + IVA

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MGN-004 Tenants | Ready | Si |
| EPIC-MGN-010 Financial | Backlog | Si (asientos contables) |
| EPIC-MGN-016 Billing | Backlog | No |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| Verticales con POS | Necesitan procesamiento de pagos |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `integrations`
- [ ] Tablas: 7 (payment_providers, payment_credentials, terminals, transactions, refunds, webhook_logs, reconciliation_batches)
- [ ] Indices: Por terminal_id, status, created_at
- [ ] RLS Policies: Si (por tenant)

**Backend:**
- [ ] Modulo: `payments`
- [ ] Services: MercadoPagoService, ClipService, PaymentProcessor, ReconciliationService
- [ ] Controllers: PaymentsController, TerminalsController, WebhooksController
- [ ] Endpoints: 20+ (CRUD terminales, procesar pago, reembolso, webhooks)
- [ ] Jobs: ReconciliationJob (diario)
- [ ] Tests: 35+

**Frontend:**
- [ ] Paginas: 5 (Terminals, Transactions, Reconciliation, ProviderConfig, TransactionDetail)
- [ ] Componentes: TerminalCard, TransactionTable, RefundForm, PaymentForm, ReconciliationWizard
- [ ] Stores: 1 (paymentsStore)

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Cambios en APIs de proveedores | Media | Alto | Versionado, abstraccion, monitoreo |
| Timeout en transacciones | Media | Alto | Retry, timeout configurable, fallback |
| Conciliacion incorrecta | Baja | Alto | Validaciones, alertas, revision manual |
| PCI DSS incumplimiento | Baja | Critico | No almacenar datos sensibles, usar tokens |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Cuentas de sandbox de MercadoPago y Clip
- [ ] Catalogo de asientos contables definido
- [x] Sin bloqueadores activos

## Definition of Done (DoD)

- [ ] Codigo implementado y revisado
- [ ] Tests pasando (unit, integration)
- [ ] Integracion MercadoPago funcional
- [ ] Integracion Clip funcional
- [ ] Webhooks procesando correctamente
- [ ] Asientos contables generandose
- [ ] Documentacion actualizada
- [ ] Inventarios actualizados
- [ ] Demo realizada
- [ ] Product Owner aprobo

---

## Documentacion Relacionada

- Requerimientos: `docs/03-requerimientos/RF-payments/`
- User Stories: `docs/05-user-stories/mgn-017/`
- DDL Spec: `docs/04-modelado/database-design/DDL-SPEC-integrations_payments.md`
- API MercadoPago: https://www.mercadopago.com.mx/developers/es/docs
- API Clip: https://developer.clip.mx/

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creacion de epica | Requirements-Analyst |
| 2025-12-05 | Completado con Stakeholders, Riesgos, DoR/DoD | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Ultima actualizacion:** 2025-12-05