# 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

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

## Flujo Principal - Agregar Tarjeta

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

## Flujos Alternativos

### FA-1: Establecer como Principal
1. Usuario tiene múltiples métodos registrados
2. Usuario selecciona "Establecer como principal"
3. Sistema actualiza `is_default = true` para el seleccionado
4. Sistema establece `is_default = false` para los demás

### FA-2: Eliminar Método de Pago
1. Usuario solicita eliminar método
2. Sistema valida que no sea el único método con suscripción activa pagada
3. Si es válido: Sistema elimina del gateway y base de datos
4. Si es el único: Sistema muestra error y sugiere agregar otro primero

### FA-3: Tarjeta Próxima a Vencer
1. Sistema detecta tarjeta que vence en 30 días
2. Sistema envía notificación al tenant owner
3. Usuario puede actualizar o agregar nueva tarjeta
4. Si no actualiza y vence: Sistema marca como inválida

### FA-4: Tarjeta Rechazada
1. Sistema intenta cobro y gateway rechaza
2. Sistema registra fallo en `billing_errors`
3. Sistema notifica al usuario
4. Usuario debe actualizar método de pago
5. 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](./RF-MGN-015-002-gestion-suscripciones-tenant.md) - Suscripciones
- [Stripe Elements Documentation](https://stripe.com/docs/payments/elements)

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