RF-MGN-015-003: Gestión de Métodos de Pago

Módulo: MGN-015 - Billing y Suscripciones Prioridad: P0 (MVP para SaaS) Story Points: 8 Estado: Definido Fecha: 2025-11-24

Descripción

El sistema debe permitir a los propietarios de tenants registrar y gestionar métodos de pago para el cobro automático de suscripciones. Se soportan tarjetas de crédito/débito como método principal, con posibilidad de extender a otros métodos según el gateway de pagos utilizado.

Actores

Actor Principal: Tenant Owner
Actores Secundarios:
- Gateway de Pagos (Stripe, Conekta, etc.)
- Sistema (validación y cobros automáticos)

Precondiciones

Usuario debe ser tenant_owner del tenant
Tenant debe tener suscripción activa o en proceso de contratación
Integración con gateway de pagos configurada

Flujo Principal - Agregar Tarjeta

Tenant Owner accede a sección de métodos de pago
Sistema muestra métodos registrados (si existen)
Usuario selecciona "Agregar método de pago"
Sistema presenta formulario seguro (iframe de gateway)
Usuario ingresa datos de tarjeta
Gateway tokeniza la información
Sistema guarda token y últimos 4 dígitos (no datos sensibles)
Sistema marca como método principal si es el primero
Sistema confirma registro exitoso

Flujos Alternativos

FA-1: Establecer como Principal

Usuario tiene múltiples métodos registrados
Usuario selecciona "Establecer como principal"
Sistema actualiza is_default = true para el seleccionado
Sistema establece is_default = false para los demás

FA-2: Eliminar Método de Pago

Usuario solicita eliminar método
Sistema valida que no sea el único método con suscripción activa pagada
Si es válido: Sistema elimina del gateway y base de datos
Si es el único: Sistema muestra error y sugiere agregar otro primero

FA-3: Tarjeta Próxima a Vencer

Sistema detecta tarjeta que vence en 30 días
Sistema envía notificación al tenant owner
Usuario puede actualizar o agregar nueva tarjeta
Si no actualiza y vence: Sistema marca como inválida

FA-4: Tarjeta Rechazada

Sistema intenta cobro y gateway rechaza
Sistema registra fallo en billing_errors
Sistema notifica al usuario
Usuario debe actualizar método de pago
Sistema reintenta según política de reintentos

Reglas de Negocio

RN-1: Datos sensibles nunca se almacenan localmente (solo tokens)
RN-2: Debe existir método principal para suscripciones de pago
RN-3: No se puede eliminar único método con suscripción activa pagada
RN-4: Métodos vencidos se marcan automáticamente como inválidos
RN-5: Plan free no requiere método de pago registrado
RN-6: Se almacena: tipo, últimos 4 dígitos, fecha vencimiento, token

Criterios de Aceptación

Tenant owner puede agregar tarjeta de crédito/débito
Sistema tokeniza datos vía gateway (no almacena PAN)
Tenant owner puede ver métodos registrados (enmascarados)
Tenant owner puede establecer método principal
Tenant owner puede eliminar métodos no principales
Sistema notifica tarjetas próximas a vencer
Sistema valida tarjeta al momento de registro
Cumplimiento PCI-DSS mediante uso de gateway

Entidades Involucradas

Principales:
- billing.payment_methods (id, tenant_id, type, provider, token, last_four, expires_at)
Relacionadas:
- billing.tenant_owners (propietario autorizado)
- billing.subscriptions (método usado para cobros)
- billing.payments (registro de transacciones)

Tipos de Método Soportados

Tipo	Descripción	Campos Específicos
card	Tarjeta crédito/débito	last_four, expires_at, brand
bank_account	Cuenta bancaria (futuro)	bank_name, last_four
oxxo_pay	Pago en OXXO (futuro)	reference

Seguridad

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Cliente   │────▶│   Gateway   │────▶│   Sistema   │
│  (Browser)  │     │  (Stripe)   │     │   (Token)   │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │   Banco     │
                    └─────────────┘

- Datos de tarjeta NUNCA pasan por nuestros servidores
- Solo almacenamos: token, last_four, expires_at, brand
- Cumplimiento PCI-DSS SAQ-A

Referencias

RF-MGN-015-002 - Suscripciones
Stripe Elements Documentation

Notas Técnicas

Tabla: billing.payment_methods
Gateway principal: Stripe (configurable)
Campos sensibles: provider_token (token del gateway, no datos de tarjeta)
Webhook: Recibir notificaciones de tarjetas actualizadas/vencidas
Soft delete: Métodos eliminados mantienen registro para auditoría

Dependencias

RF Requeridos: RF-MGN-015-002 (Suscripciones)
Bloqueante para: RF-MGN-015-004 (Facturación y Cobros)

5.3 KiB Raw Blame History