michangarrito/docs/01-epicas/MCH-020-pagos-suscripcion.md

---
id: EPIC-MCH-020
type: Epic
title: "MCH-020: Pagos de Suscripcion"
code: MCH-020
status: Completado
phase: 5
priority: P0
story_points: 34
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
dependencies:
  blocks: []
  depends_on: []
---

# MCH-020: Pagos de Suscripcion

## Metadata
- **Codigo:** MCH-020
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** Completado
- **Story Points:** 34
- **Fecha completado:** 2026-01-10

## Descripcion

Sistema completo de pagos para suscripciones y tokens: Stripe para tarjetas y OXXO, In-App Purchase para iOS/Android, y manejo de pagos fallidos.

## Objetivos

1. Pagos con tarjeta (Stripe)
2. Pagos en OXXO (Stripe)
3. In-App Purchase iOS
4. In-App Purchase Android
5. Manejo de pagos fallidos

## Alcance

### Incluido
- Stripe Checkout
- OXXO Pay (via Stripe)
- Apple In-App Purchase
- Google Play Billing
- Reintentos automaticos
- Recibos por email

### Excluido
- PayPal
- Transferencia bancaria manual
- Criptomonedas

## Metodos de Pago

### Stripe - Tarjeta
```
Comision: ~3.6% + $3 MXN
Confirmacion: Inmediata
Uso: Web y App (via Stripe SDK)
```

### Stripe - OXXO
```
Comision: ~$10-15 MXN fijo
Confirmacion: 24-72 horas
Uso: Cliente paga en OXXO
Vencimiento: 3 dias
```

### Apple In-App Purchase
```
Comision: 15-30%
Confirmacion: Inmediata
Uso: App iOS
Nota: Obligatorio para apps iOS
```

### Google Play Billing
```
Comision: 15%
Confirmacion: Inmediata
Uso: App Android
```

## Flujos de Pago

### Pago con Tarjeta
```
1. Usuario selecciona plan/tokens
2. Elige "Pagar con tarjeta"
3. Stripe Checkout se abre
4. Ingresa datos de tarjeta
5. Pago procesado
6. Redirige a app con confirmacion
7. Suscripcion/tokens activados
```

### Pago en OXXO
```
1. Usuario selecciona plan/tokens
2. Elige "Pagar en OXXO"
3. Se genera referencia OXXO
4. Se muestra:
   - Monto a pagar
   - Referencia/codigo de barras
   - Fecha limite
5. Usuario va a OXXO y paga
6. Webhook confirma pago (horas despues)
7. Suscripcion/tokens activados
8. Notificacion al usuario
```

### In-App Purchase (iOS)
```
1. Usuario abre tienda en app
2. Selecciona producto
3. StoreKit muestra sheet de Apple
4. Usuario confirma con Face ID
5. Apple procesa pago
6. App recibe notificacion
7. Backend valida con Apple
8. Suscripcion/tokens activados
```

## Modelo de Datos

### Tablas Adicionales

**payment_methods**
- id, tenant_id, type (card/oxxo/iap)
- provider, last4, brand
- is_default, stripe_pm_id

**payments**
- id, tenant_id, type (subscription/tokens)
- amount, currency, status
- provider, provider_id
- metadata (JSONB)

**oxxo_vouchers**
- id, payment_id, reference
- barcode_url, expires_at
- status

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /payments/create-checkout | Crear sesion Stripe |
| POST | /payments/create-oxxo | Generar voucher OXXO |
| POST | /payments/verify-iap | Verificar IAP |
| GET | /payments/methods | Metodos guardados |
| POST | /payments/methods | Agregar metodo |
| DELETE | /payments/methods/:id | Eliminar metodo |
| POST | /payments/webhook/stripe | Webhook Stripe |
| POST | /payments/webhook/apple | Webhook Apple |
| POST | /payments/webhook/google | Webhook Google |

## Manejo de Pagos Fallidos

### Reintentos Automaticos
```
Dia 1: Primer intento fallido
Dia 3: Segundo intento
Dia 5: Tercer intento
Dia 7: Cuarto intento + alerta
Dia 10: Suspension de servicio
```

### Notificaciones
```
[Pago fallido - Dia 1]
"No pudimos procesar tu pago de $99.
Actualiza tu metodo de pago para
continuar usando MiChangarrito.

[Actualizar pago]"

[Ultimo aviso - Dia 7]
"⚠️ Tu suscripcion sera cancelada
en 3 dias si no actualizas tu pago.

[Actualizar pago ahora]"
```

## UI Components

### PaymentMethodSelector
- Radio buttons de metodos
- Tarjeta, OXXO, o guardados
- Agregar nueva tarjeta

### OXXOVoucher
- Codigo de barras
- Monto y referencia
- Instrucciones
- Boton compartir

### PaymentHistory
- Lista de pagos
- Estado y fecha
- Descargar recibo

## Historias de Usuario

### MCH-US-190: Pagos con Tarjeta via Stripe Checkout
**Story Points:** 8

**Como** propietario de negocio
**Quiero** pagar mi suscripcion o tokens con tarjeta de credito/debito
**Para** activar mi plan de manera inmediata y segura

#### Criterios de Aceptacion
- [CA-190-1] El sistema redirige a Stripe Checkout al seleccionar pago con tarjeta
- [CA-190-2] Se soportan tarjetas Visa, Mastercard y American Express
- [CA-190-3] La confirmacion del pago es inmediata tras procesamiento exitoso
- [CA-190-4] El usuario recibe recibo por email automaticamente
- [CA-190-5] La suscripcion/tokens se activan inmediatamente tras pago exitoso

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-190-01 | Configurar Stripe Checkout Session en backend | 4h |
| MCH-TT-190-02 | Implementar stripe-checkout.service.ts | 6h |
| MCH-TT-190-03 | Crear endpoint POST /payments/create-checkout | 3h |
| MCH-TT-190-04 | Integrar Stripe.js en frontend | 4h |
| MCH-TT-190-05 | Implementar flujo de redireccion y confirmacion | 3h |
| MCH-TT-190-06 | Configurar webhook para eventos de pago | 4h |

---

### MCH-US-191: Pagos en OXXO con Voucher
**Story Points:** 5

**Como** propietario de negocio sin tarjeta bancaria
**Quiero** generar un voucher para pagar en OXXO
**Para** poder adquirir mi suscripcion usando efectivo

#### Criterios de Aceptacion
- [CA-191-1] Se genera referencia OXXO con codigo de barras valido
- [CA-191-2] El voucher muestra monto, referencia y fecha de vencimiento (3 dias)
- [CA-191-3] El usuario puede compartir el voucher via imagen o PDF
- [CA-191-4] El sistema procesa webhook de confirmacion de OXXO (24-72h)
- [CA-191-5] La suscripcion/tokens se activan automaticamente tras confirmacion

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-191-01 | Implementar oxxo.service.ts con Stripe OXXO Pay | 4h |
| MCH-TT-191-02 | Crear endpoint POST /payments/create-oxxo | 2h |
| MCH-TT-191-03 | Disenar componente OXXOVoucher con codigo de barras | 4h |
| MCH-TT-191-04 | Implementar funcionalidad de compartir voucher | 2h |
| MCH-TT-191-05 | Configurar webhook para confirmacion OXXO | 3h |
| MCH-TT-191-06 | Implementar notificacion push al confirmar pago | 2h |

---

### MCH-US-192: In-App Purchase para iOS
**Story Points:** 8

**Como** usuario de la app iOS
**Quiero** comprar suscripciones o tokens desde la app
**Para** no tener que salir de la aplicacion para pagar

#### Criterios de Aceptacion
- [CA-192-1] Los productos estan configurados en App Store Connect
- [CA-192-2] StoreKit muestra la hoja de compra nativa de Apple
- [CA-192-3] El usuario puede confirmar con Face ID/Touch ID
- [CA-192-4] El backend valida el receipt con Apple Server
- [CA-192-5] Las suscripciones se renuevan automaticamente via Apple

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-192-01 | Configurar productos en App Store Connect | 2h |
| MCH-TT-192-02 | Implementar StoreKit 2 en app iOS (React Native) | 6h |
| MCH-TT-192-03 | Implementar apple-iap.service.ts en backend | 5h |
| MCH-TT-192-04 | Crear endpoint POST /payments/verify-iap | 3h |
| MCH-TT-192-05 | Configurar Server Notifications de Apple | 3h |
| MCH-TT-192-06 | Implementar validacion de receipts con Apple API | 4h |

---

### MCH-US-193: In-App Purchase para Android
**Story Points:** 6

**Como** usuario de la app Android
**Quiero** comprar suscripciones o tokens desde la app
**Para** usar el metodo de pago configurado en Google Play

#### Criterios de Aceptacion
- [CA-193-1] Los productos estan configurados en Google Play Console
- [CA-193-2] Google Play Billing muestra la UI nativa de compra
- [CA-193-3] El backend valida la compra con Google Play API
- [CA-193-4] Las suscripciones se renuevan automaticamente via Google
- [CA-193-5] Se manejan correctamente los estados de compra pendiente

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-193-01 | Configurar productos en Google Play Console | 2h |
| MCH-TT-193-02 | Implementar Google Play Billing Library en app | 5h |
| MCH-TT-193-03 | Implementar google-billing.service.ts en backend | 4h |
| MCH-TT-193-04 | Crear endpoint para validacion de compras Google | 3h |
| MCH-TT-193-05 | Configurar Real-time Developer Notifications | 3h |
| MCH-TT-193-06 | Manejar estados de compra pendiente (PENDING) | 2h |

---

### MCH-US-194: Manejo de Pagos Fallidos con Reintentos
**Story Points:** 5

**Como** sistema
**Quiero** reintentar automaticamente pagos fallidos
**Para** maximizar la retencion de suscriptores y reducir churn involuntario

#### Criterios de Aceptacion
- [CA-194-1] Se ejecutan reintentos en dias 1, 3, 5 y 7 tras fallo inicial
- [CA-194-2] Se envia notificacion push y email en cada intento fallido
- [CA-194-3] El dia 7 se envia alerta de suspension inminente
- [CA-194-4] El dia 10 se suspende el servicio si no hay pago exitoso
- [CA-194-5] El usuario puede actualizar metodo de pago en cualquier momento

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-194-01 | Implementar job de reintentos programados (cron) | 4h |
| MCH-TT-194-02 | Crear templates de notificaciones de pago fallido | 2h |
| MCH-TT-194-03 | Implementar logica de suspension de servicio | 3h |
| MCH-TT-194-04 | Crear pantalla de actualizacion de metodo de pago | 4h |
| MCH-TT-194-05 | Implementar webhook para invoice.payment_failed | 2h |
| MCH-TT-194-06 | Agregar metricas de dunning para analytics | 2h |

---

### MCH-US-195: Gestion de Metodos de Pago Guardados
**Story Points:** 3

**Como** propietario de negocio
**Quiero** guardar y gestionar mis metodos de pago
**Para** facilitar pagos futuros sin reingresar datos

#### Criterios de Aceptacion
- [CA-195-1] El usuario puede guardar tarjetas de forma segura (tokenizadas)
- [CA-195-2] Se muestra lista de metodos guardados con ultimos 4 digitos
- [CA-195-3] El usuario puede seleccionar un metodo de pago por defecto
- [CA-195-4] El usuario puede eliminar metodos de pago guardados
- [CA-195-5] Los datos de tarjeta nunca se almacenan en nuestros servidores

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-195-01 | Implementar tabla payment_methods en base de datos | 2h |
| MCH-TT-195-02 | Crear endpoints CRUD para metodos de pago | 3h |
| MCH-TT-195-03 | Integrar Stripe SetupIntent para guardar tarjetas | 3h |
| MCH-TT-195-04 | Disenar componente PaymentMethodSelector | 3h |
| MCH-TT-195-05 | Implementar pantalla de gestion de metodos de pago | 3h |

---

### Resumen de Historias de Usuario

| ID | Historia | SP | Prioridad |
|----|----------|----|-----------|
| MCH-US-190 | Pagos con Tarjeta via Stripe Checkout | 8 | P0 |
| MCH-US-191 | Pagos en OXXO con Voucher | 5 | P0 |
| MCH-US-192 | In-App Purchase para iOS | 8 | P0 |
| MCH-US-193 | In-App Purchase para Android | 6 | P0 |
| MCH-US-194 | Manejo de Pagos Fallidos con Reintentos | 5 | P1 |
| MCH-US-195 | Gestion de Metodos de Pago Guardados | 3 | P1 |
| **Total** | | **34** | |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| Stripe Checkout | En progreso | `services/stripe-checkout.service.ts` |
| OXXO Pay | Pendiente | `services/oxxo.service.ts` |
| Apple IAP | Pendiente | `services/apple-iap.service.ts` |
| Google Billing | Pendiente | `services/google-billing.service.ts` |
| Payment UI | Pendiente | `components/payments/` |

## Dependencias

### Depende de
- MCH-005 (Stripe base)
- MCH-018 (Suscripciones)
- MCH-019 (Tokens)

### Bloquea a
- Ninguno

## Criterios de Aceptacion

- [x] Pago con tarjeta funciona
- [x] OXXO genera voucher correcto
- [x] IAP iOS funciona
- [x] IAP Android funciona
- [x] Pagos fallidos se reintentan
- [x] Notificaciones se envian

## Configuracion Stripe

```typescript
{
  stripe: {
    secretKey: process.env.STRIPE_SECRET_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
    oxxo: {
      enabled: true,
      expires_after_days: 3
    },
    retry: {
      max_attempts: 4,
      days_between: [0, 3, 5, 7]
    }
  }
}
```

---

**Ultima actualizacion:** 2026-01-17