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

id	type	title	code	status	phase	priority	story_points	created_at	updated_at	simco_version	dependencies
EPIC-MCH-020	Epic	MCH-020: Pagos de Suscripcion	MCH-020	Completado	5	P0	34	2026-01-10	2026-01-17	4.0.1	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

• 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-17