---
id: "US-PAY-002"
title: "Suscribirse a Plan"
type: "User Story"
status: "Done"
priority: "Media"
epic: "OQI-005"
project: "trading-platform"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-PAY-002: Suscribirse a Plan

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** ✅ Implementado
**Story Points:** 5
**Prioridad:** P0 (Crítica)
**Épica:** [OQI-005](../_MAP.md)

---

## Historia de Usuario

**Como** usuario registrado de Trading Platform
**Quiero** suscribirme a un plan de pago (Basic, Pro o Premium)
**Para** acceder a funcionalidades premium y mejorar mi experiencia de trading

---

## Criterios de Aceptación

### AC-001: Selección de Plan

**Dado** que estoy en la página de pricing
**Cuando** hago click en "Suscribirme" en un plan (Basic/Pro/Premium)
**Entonces** debería:
- Ser redirigido a página de checkout
- Ver el plan seleccionado claramente destacado
- Ver el precio mensual y total del primer mes
- Ver nota de trial de 7 días (si aplica para Pro/Premium)

### AC-002: Formulario de Pago

**Dado** que estoy en la página de checkout de suscripción
**Cuando** veo el formulario
**Entonces** debería ver:
- Resumen del plan seleccionado
- Stripe Elements para ingresar tarjeta
  - Número de tarjeta
  - Fecha de expiración (MM/YY)
  - CVC
  - Nombre del titular
- Detección automática de marca de tarjeta (Visa, MC, Amex)
- Checkbox "Acepto los términos del servicio y política de reembolso"
- Botón "Comenzar Trial de 7 Días" (Pro/Premium) o "Suscribirme" (Basic)

### AC-003: Trial Period (Pro/Premium)

**Dado** que me estoy suscribiendo a Pro o Premium
**Cuando** completo el checkout
**Entonces** debería:
- NO ser cobrado inmediatamente
- Ver confirmación: "Trial iniciado. No se te cobrará hasta el DD/MM/YYYY"
- Tener acceso completo al plan durante 7 días
- Poder cancelar durante trial sin cargo

### AC-004: Pago Inmediato (Basic)

**Dado** que me estoy suscribiendo a Basic
**Cuando** completo el checkout
**Entonces** debería:
- Ser cobrado $19 USD inmediatamente
- Ver confirmación: "Suscripción activada. Próximo cobro: DD/MM/YYYY"
- Tener acceso completo al plan Basic

### AC-005: Validación de Tarjeta

**Dado** que estoy ingresando datos de tarjeta
**Cuando** ingreso información inválida
**Entonces** debería ver mensajes de error específicos:
- "Número de tarjeta inválido"
- "Fecha de expiración inválida"
- "Código de seguridad inválido"
- "Nombre del titular requerido"

### AC-006: Procesamiento 3D Secure

**Dado** que mi tarjeta requiere autenticación 3DS
**Cuando** confirmo la suscripción
**Entonces** debería:
- Ver modal/iframe del banco para autenticar
- Completar autenticación (SMS, app bancaria, etc.)
- Recibir confirmación después de autenticación exitosa
- Ver error si autenticación falla

### AC-007: Confirmación de Suscripción

**Dado** que completé el pago exitosamente
**Cuando** se confirma la suscripción
**Entonces** debería:
- Ver página de confirmación con mensaje de éxito
- Recibir email de confirmación con:
  - Detalles del plan
  - Fecha de primer cobro (o cobro inmediato)
  - Link para gestionar suscripción
  - Factura adjunta (si fue cobro inmediato)
- Ver badge del plan en mi perfil
- Tener acceso a funcionalidades premium

### AC-008: Ya Tiene Suscripción Activa

**Dado** que ya tengo una suscripción activa
**Cuando** intento suscribirme a otro plan
**Entonces** debería:
- Ver mensaje: "Ya tienes una suscripción activa a {plan}"
- Ver opción "Cambiar Plan" en lugar de "Suscribirse"
- Ser redirigido a página de gestión de suscripción

### AC-009: Error de Pago

**Dado** que mi tarjeta es rechazada
**Cuando** intento completar la suscripción
**Entonces** debería:
- Ver mensaje de error específico:
  - "Tu tarjeta fue rechazada. Intenta con otra tarjeta."
  - "Fondos insuficientes. Verifica tu saldo."
  - "Tarjeta expirada. Usa una tarjeta vigente."
- Permanecer en página de checkout
- Poder editar datos de tarjeta e intentar de nuevo
- NO crear suscripción en estado incompleto

### AC-010: Abandono de Checkout

**Dado** que estoy en checkout pero no completo el pago
**Cuando** cierro la página
**Entonces** debería:
- NO ser cobrado
- NO tener suscripción creada
- Recibir email recordatorio después de 24h (opcional)

---

## Mockup

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                      Suscripción a Plan Pro                 │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Plan Pro                                    $49/mes│   │
│  │  ───────────────────────────────────────────────────│   │
│  │  ✅ Predicciones avanzadas con IA                   │   │
│  │  ✅ Todos los cursos                                │   │
│  │  ✅ Indicadores técnicos premium                    │   │
│  │  ✅ Alertas personalizadas                          │   │
│  │                                                     │   │
│  │  🎉 7 días gratis - Luego $49/mes                   │   │
│  │     Cancela cuando quieras                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Método de Pago                                     │   │
│  │                                                     │   │
│  │  Número de tarjeta                                  │   │
│  │  ┌───────────────────────────────────────────────┐ │   │
│  │  │ 4242 4242 4242 4242                   [Visa] │ │   │
│  │  └───────────────────────────────────────────────┘ │   │
│  │                                                     │   │
│  │  ┌──────────────────────┐ ┌──────────────────────┐ │   │
│  │  │ Vencimiento          │ │ CVC                  │ │   │
│  │  │ ┌──────────────────┐ │ │ ┌──────────────────┐ │ │   │
│  │  │ │ 12 / 25          │ │ │ │ 123              │ │ │   │
│  │  │ └──────────────────┘ │ │ └──────────────────┘ │ │   │
│  │  └──────────────────────┘ └──────────────────────┘ │   │
│  │                                                     │   │
│  │  Nombre del titular                                 │   │
│  │  ┌───────────────────────────────────────────────┐ │   │
│  │  │ Juan Pérez                                    │ │   │
│  │  └───────────────────────────────────────────────┘ │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ☑ Acepto los términos del servicio y política de          │
│    reembolso                                                │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         Comenzar Trial de 7 Días - Gratis           │   │
│  │                                                     │   │
│  │  No se te cobrará hasta el 12/12/2025               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  🔒 Pago seguro procesado por Stripe                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Flujo de Suscripción (Gherkin)

```gherkin
Feature: Suscripción a Plan Pro

  Scenario: Suscripción exitosa con trial de 7 días
    Given que soy usuario registrado con email "juan@example.com"
    And estoy logueado
    And NO tengo suscripción activa
    When navego a la página de pricing
    And hago click en "Suscribirme" en el plan Pro
    Then debería ver la página de checkout con plan "Pro" seleccionado
    And debería ver el mensaje "7 días gratis - Luego $49/mes"

    When ingreso número de tarjeta "4242 4242 4242 4242"
    And ingreso fecha de vencimiento "12/25"
    And ingreso CVC "123"
    And ingreso nombre "Juan Pérez"
    And marco checkbox de términos
    And hago click en "Comenzar Trial de 7 Días"
    Then debería ver indicador de procesamiento
    And después de 2-5 segundos debería ver página de confirmación
    And debería ver mensaje "¡Trial iniciado! No se te cobrará hasta el 12/12/2025"

    And debería recibir email con asunto "Bienvenido a Trading Platform Pro"
    And mi perfil debería mostrar badge "Pro"
    And debería tener acceso a predicciones avanzadas
    And debería tener acceso a todos los cursos

  Scenario: Tarjeta rechazada
    Given que estoy en checkout de plan Pro
    When ingreso tarjeta "4000 0000 0000 0002" (rechazada)
    And completo formulario y confirmo
    Then debería ver error "Tu tarjeta fue rechazada. Intenta con otra."
    And debería permanecer en página de checkout
    And NO debería tener suscripción creada

  Scenario: Usuario ya tiene suscripción
    Given que tengo suscripción activa a "Basic"
    When intento suscribirme a "Pro"
    Then debería ver mensaje "Ya tienes una suscripción activa a Basic"
    And debería ver botón "Cambiar a Pro" en lugar de "Suscribirme"
```

---

## Notas Técnicas

### Frontend

- Componente: `apps/frontend/src/pages/SubscriptionCheckout.tsx`
- Cargar Stripe.js: `@stripe/stripe-js`
- Elementos: `@stripe/react-stripe-js`
- Pasos:
  1. Fetch plan details
  2. Inicializar Stripe Elements
  3. Recopilar datos de tarjeta
  4. Llamar backend para crear suscripción
  5. Confirmar pago con `stripe.confirmCardPayment()` si requiere

### Backend

- Endpoint: `POST /api/v1/payments/subscriptions`
- Request:
```json
{
  "plan": "pro",
  "paymentMethodId": "pm_xxx",
  "trial": true
}
```

- Response (Success):
```json
{
  "subscription": {
    "id": "uuid",
    "plan": "pro",
    "status": "trialing",
    "trialEnd": "2025-12-12T00:00:00Z",
    "currentPeriodEnd": "2025-12-12T00:00:00Z"
  }
}
```

- Response (Requires Action - 3DS):
```json
{
  "requiresAction": true,
  "clientSecret": "seti_xxx_secret_yyy",
  "subscriptionId": "sub_xxx"
}
```

### Database

- Crear registro en `billing.subscriptions`
- Actualizar `users.subscription_plan`
- Crear `billing.payments` si hay cobro inmediato

### Email Templates

**Subject:** Bienvenido a Trading Platform Pro

```
Hola Juan,

¡Bienvenido a Trading Platform Pro! 🎉

Tu trial de 7 días ha comenzado. Tienes acceso completo a:
✅ Predicciones avanzadas con IA
✅ Todos los cursos
✅ Indicadores técnicos premium
✅ Alertas personalizadas

Tu primer cobro será el 12/12/2025 por $49 USD.

Puedes cancelar en cualquier momento desde:
[Gestionar Suscripción]

¿Preguntas? Escríbenos a support@trading.com

Saludos,
El equipo de Trading Platform
```

---

## Dependencias

- [US-PAY-001: Ver Planes Disponibles](US-PAY-001-ver-planes.md)
- [US-PAY-006: Agregar Método de Pago](US-PAY-006-agregar-metodo-pago.md)

---

## Requerimientos Relacionados

- [RF-PAY-001: Sistema de Planes y Suscripciones](../requerimientos/RF-PAY-001-suscripciones.md)
- [RF-PAY-002: Checkout con Stripe Elements](../requerimientos/RF-PAY-002-checkout.md)

---

## Tareas Técnicas

### Frontend
- [ ] Crear página `SubscriptionCheckout.tsx`
- [ ] Integrar Stripe Elements (CardElement)
- [ ] Implementar flujo de confirmación 3DS
- [ ] Agregar validación de formulario
- [ ] Página de confirmación exitosa
- [ ] Manejo de errores con mensajes claros

### Backend
- [ ] Endpoint `POST /api/v1/payments/subscriptions`
- [ ] Validar que usuario no tenga suscripción activa
- [ ] Crear Customer en Stripe si no existe
- [ ] Adjuntar PaymentMethod a Customer
- [ ] Crear Subscription con trial si aplica
- [ ] Guardar en BD (subscriptions)
- [ ] Enviar email de bienvenida
- [ ] Webhook `customer.subscription.created`

### Testing
- [ ] Test: Suscripción con trial exitosa (Pro/Premium)
- [ ] Test: Suscripción sin trial exitosa (Basic)
- [ ] Test: Tarjeta rechazada muestra error
- [ ] Test: 3DS funciona correctamente
- [ ] Test: Usuario con suscripción activa no puede crear otra
- [ ] Test: Email de bienvenida se envía
- [ ] Test: Acceso premium se otorga inmediatamente
