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

MCH-005: Integraciones de Pago

Metadata

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

---

Ultima actualizacion: 2026-01-07