rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-core/docs/08-epicas/EPIC-MGN-017-payments.md

6.6 KiB
Raw Permalink Blame History

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

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