rckrdmrd
8a540b4e94
- MCH-002: 4 HU (MCH-US-010 a MCH-US-013), 13 SP - MCH-003: 5 HU (MCH-US-020 a MCH-US-024), 8 SP - MCH-004: 6 HU (MCH-US-030 a MCH-US-035), 21 SP - MCH-005: 4 HU (MCH-US-040 a MCH-US-043), 13 SP Formato: Como/Quiero/Para + Criterios [CA-XXX-N] + Tareas [MCH-TT-XXX-NN] Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
306 lines
8.1 KiB
Markdown
306 lines
8.1 KiB
Markdown
---
|
|
id: EPIC-MCH-005
|
|
type: Epic
|
|
title: "MCH-005: Integraciones de Pago"
|
|
code: MCH-005
|
|
status: Completado
|
|
phase: 1
|
|
priority: P0
|
|
story_points: 13
|
|
created_at: 2026-01-06
|
|
updated_at: 2026-01-17
|
|
simco_version: "4.0.1"
|
|
dependencies:
|
|
blocks: ["MCH-018", "MCH-020"]
|
|
depends_on: ["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
|
|
|
|
- [x] Mercado Pago procesa pagos
|
|
- [x] Webhooks se reciben correctamente
|
|
- [x] Efectivo registra correctamente
|
|
- [x] Stripe funciona para suscripciones
|
|
- [x] Conciliacion de pagos funciona
|
|
|
|
## Configuracion por Tenant
|
|
|
|
```typescript
|
|
// 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
|