6.6 KiB
6.6 KiB
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)
- Historias de usuario definidas
- Criterios de aceptacion claros
- Dependencias identificadas
- Estimacion completada
- Cuentas de sandbox de MercadoPago y Clip
- Catalogo de asientos contables definido
- 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