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

• Pago con tarjeta funciona
• OXXO genera voucher correcto
• IAP iOS funciona
• IAP Android funciona
• Pagos fallidos se reintentan
• Notificaciones se envian

Configuracion Stripe

{
  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