michangarrito/docs/01-epicas/MCH-005-integraciones-pago.md

id	type	title	code	status	phase	priority	story_points	created_at	updated_at	simco_version	dependencies
EPIC-MCH-005	Epic	MCH-005: Integraciones de Pago	MCH-005	Completado	1	P0	13	2026-01-06	2026-01-17	4.0.1	blocks depends_on MCH-018 MCH-020 MCH-001 MCH-002 MCH-004

MCH-005: Integraciones de Pago

Metadata

• Codigo: MCH-005
• Fase: 1 - MVP Core
• Prioridad: P0
• Estado: Completado
• Story Points: 13
• 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

• Mercado Pago procesa pagos
• Webhooks se reciben correctamente
• Efectivo registra correctamente
• Stripe funciona para suscripciones
• Conciliacion de pagos funciona

Configuracion por Tenant

// 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

---

Historias de Usuario

MCH-US-040: Integracion Mercado Pago Point

Como empleado de tienda Quiero procesar pagos con tarjeta usando el lector Mercado Pago Point Para ofrecer una opcion de pago rapida y segura a los clientes

Story Points: 3

Criterios de Aceptacion:

• [CA-040-1] ✅ Configuracion de credenciales Mercado Pago por tenant
• [CA-040-2] ✅ Conexion bluetooth con dispositivo Point establecida
• [CA-040-3] ✅ Monto enviado correctamente a terminal
• [CA-040-4] ✅ Webhook de confirmacion procesado en <5 segundos
• [CA-040-5] ✅ Venta marcada como pagada automaticamente

Tareas:

ID	Tarea	Tipo	Estado
MCH-TT-040-01	Configurar SDK Mercado Pago	Backend	Completado
MCH-TT-040-02	Implementar MercadoPagoProvider	Backend	Completado
MCH-TT-040-03	Endpoint webhook MercadoPago	Backend	Completado
MCH-TT-040-04	UI seleccion Mercado Pago en POS	Frontend	Completado
MCH-TT-040-05	Tests de integracion	Test	Completado

---

MCH-US-041: Integracion Clip

Como empleado de tienda Quiero procesar pagos con tarjeta usando terminal Clip Para tener una alternativa de pago con tarjeta

Story Points: 3

Criterios de Aceptacion:

• [CA-041-1] ✅ Configuracion de credenciales Clip por tenant
• [CA-041-2] ✅ Envio de monto a terminal Clip
• [CA-041-3] ✅ Recepcion de webhook de confirmacion
• [CA-041-4] ✅ Manejo de errores y rechazos de tarjeta
• [CA-041-5] ✅ Registro de transaccion en base de datos

Tareas:

ID	Tarea	Tipo	Estado
MCH-TT-041-01	Implementar ClipProvider	Backend	Completado
MCH-TT-041-02	Endpoint webhook Clip	Backend	Completado
MCH-TT-041-03	UI seleccion Clip en POS	Frontend	Completado
MCH-TT-041-04	Manejo de errores de pago	Backend	Completado

---

MCH-US-042: Registro de Pagos en Efectivo

Como empleado de tienda Quiero registrar pagos en efectivo con calculo automatico de cambio Para mantener control preciso de la caja

Story Points: 2

Criterios de Aceptacion:

• [CA-042-1] ✅ Seleccion de metodo de pago "Efectivo" en POS
• [CA-042-2] ✅ Input para monto recibido del cliente
• [CA-042-3] ✅ Calculo automatico de cambio a devolver
• [CA-042-4] ✅ Actualizacion de saldo en caja
• [CA-042-5] ✅ Venta registrada con metodo efectivo

Tareas:

ID	Tarea	Tipo	Estado
MCH-TT-042-01	Logica de calculo de cambio	Backend	Completado
MCH-TT-042-02	UI pago efectivo en PaymentModal	Frontend	Completado
MCH-TT-042-03	Integracion con corte de caja	Backend	Completado

---

MCH-US-043: Stripe para Suscripciones y OXXO

Como sistema Quiero procesar pagos de suscripciones y OXXO via Stripe Para habilitar cobros recurrentes y pago en tiendas de conveniencia

Story Points: 5

Criterios de Aceptacion:

• [CA-043-1] ✅ Configuracion de Stripe API keys por ambiente
• [CA-043-2] ✅ Creacion de intenciones de pago (PaymentIntent)
• [CA-043-3] ✅ Generacion de referencias OXXO con codigo de barras
• [CA-043-4] ✅ Procesamiento de webhooks Stripe (payment_intent.succeeded)
• [CA-043-5] ✅ Soporte para pagos recurrentes de suscripciones
• [CA-043-6] ✅ Confirmacion de pago OXXO en 24-48h via webhook

Tareas:

ID	Tarea	Tipo	Estado
MCH-TT-043-01	Implementar StripeProvider	Backend	Completado
MCH-TT-043-02	Endpoint crear PaymentIntent	Backend	Completado
MCH-TT-043-03	Endpoint generar referencia OXXO	Backend	Completado
MCH-TT-043-04	Webhook Stripe multiproposito	Backend	Completado
MCH-TT-043-05	Integracion con modulo suscripciones	Backend	Completado
MCH-TT-043-06	Tests unitarios Stripe	Test	Completado

---

Resumen de Story Points

Historia	SP	Estado
MCH-US-040: Integracion Mercado Pago Point	3	Completado
MCH-US-041: Integracion Clip	3	Completado
MCH-US-042: Registro de Pagos en Efectivo	2	Completado
MCH-US-043: Stripe para Suscripciones y OXXO	5	Completado
TOTAL	13	100%

---

Ultima actualizacion: 2026-01-17