michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-020-pagos-suscripcion.md

# MCH-020: Pagos de Suscripcion

## Metadata
- **Codigo:** MCH-020
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** Completado
- **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

## 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-10