# Módulo Payments

**Epic:** OQI-005 - Pagos Stripe
**Progreso:** 50%
**Responsable:** Backend + Payments Team

## Descripción

El módulo de pagos proporciona un sistema completo de billing y suscripciones integrado con Stripe. Gestiona planes de precios (free, basic, pro, premium, enterprise), payment methods, facturas, wallet system para deposits/withdrawals, y tracking de uso de recursos. Es crítico para la monetización de la plataforma.

El sistema incluye soporte para cupones de descuento, facturación prorrateada en cambios de plan, y un portal de cliente Stripe para gestión autónoma de suscripciones.

## Componentes

### Páginas

- `Pricing.tsx` - Página de planes con toggle monthly/yearly, tabla comparativa, FAQ, y checkout integration
- `Billing.tsx` - Dashboard de facturación con 4 tabs: Overview (subscription), Payment Methods, Invoices, Wallet
- `CheckoutSuccess.tsx` - Página de confirmación post-pago con detalles de suscripción y próxima fecha de cobro
- `CheckoutCancel.tsx` - Página mostrada cuando usuario abandona checkout con opciones de ayuda y reintento

### Display Components (4)

- `PricingCard.tsx` - Tarjeta de plan individual con precio, features, límites grid, y CTA button (muestra badge "Popular" y highlight de plan actual)
- `SubscriptionCard.tsx` - Detalle de suscripción activa: plan, status badge, período de facturación, próximo cargo, trial info, resumen de features
- `WalletCard.tsx` - Visualización de balance de wallet (available/pending/reserved), lista de transacciones recientes con iconos y timestamps
- `UsageProgress.tsx` - Progress bars para límites de uso (API calls, courses, paper trades, watchlist) con porcentaje y estados de warning

### Modal Components (2)

- `WalletDepositModal.tsx` - Modal para depositar fondos: input de monto, presets (50/100/250/500/1000), selector de payment method, estado de éxito
- `WalletWithdrawModal.tsx` - Modal para retiros: input de monto, validación de balance disponible, selección de cuenta bancaria destino

### Form Components (3)

- `PaymentMethodForm.tsx` - Formulario para agregar tarjeta de crédito via Stripe Elements (número, expiry, CVC)
- `BillingInfoForm.tsx` - Edición de dirección de facturación e info de empresa (nombre, email, dirección, ciudad, estado, código postal, país)
- `CouponForm.tsx` - Input de código de cupón con validación mostrando tipo y monto de descuento

### List/Detail Components (5)

- `InvoiceList.tsx` - Tabla paginada de invoices con filtrado, búsqueda, status badges, acciones de view/download
- `InvoiceDetail.tsx` - Vista completa de factura con breakdown de line items, estado de pago, fechas, y descarga de PDF
- `PaymentMethodsList.tsx` - Lista de payment methods guardados con botón star para set-as-default y opción de delete
- `TransactionHistory.tsx` - Tabla paginada de transacciones de wallet con tipo, monto, estado y fecha

### Advanced Components (1)

- `SubscriptionUpgradeFlow.tsx` - Modal para cambio de plan con comparación side-by-side, cálculo de crédito prorrateado, preview de fecha efectiva

## Estructura de Carpetas

```
modules/payments/
├── components/
│   └── (15 componentes organizados por tipo)
├── pages/
│   ├── Pricing.tsx
│   ├── Billing.tsx
│   ├── CheckoutSuccess.tsx
│   └── CheckoutCancel.tsx
└── README.md
```

**Servicios y estado compartidos:**
- **Components:** `components/payments/` (organizados por tipo)
- **Service:** `services/payment.service.ts` (Axios)
- **Store:** `stores/paymentStore.ts` (Zustand con Redux DevTools)
- **Types:** `types/payment.types.ts`

## APIs Consumidas

### Plans & Subscriptions (Base URL: `/api/v1`)

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/plans` | GET | Obtener todos los planes activos |
| `/payments/plans/{slug}` | GET | Obtener plan por slug |
| `/payments/subscription` | GET | Suscripción activa del usuario |
| `/payments/subscription/history` | GET | Historial de suscripciones pasadas |
| `/payments/subscriptions` | POST | Crear nueva suscripción |
| `/payments/subscription/cancel` | POST | Cancelar suscripción (inmediato o al final del período) |
| `/payments/subscription/resume` | POST | Reactivar suscripción cancelada |
| `/payments/subscription/change-plan` | POST | Upgrade/downgrade a plan diferente |

### Checkout & Billing Portal

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/checkout` | POST | Crear Stripe checkout session |
| `/payments/billing-portal` | POST | Crear Stripe billing portal session |

### Payment Methods

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/methods` | GET | Listar payment methods guardados |
| `/payments/methods` | POST | Agregar nuevo payment method |
| `/payments/methods/default` | POST | Establecer payment method por defecto |
| `/payments/methods/{paymentMethodId}` | DELETE | Eliminar payment method |

### Payments & Invoices

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/history` | GET | Historial de pagos (paginado) |
| `/payments/invoices` | GET | Lista de facturas (paginado) |
| `/payments/invoices/{invoiceId}` | GET | Detalle de factura |
| `/payments/invoices/{invoiceId}/pdf` | GET | Descargar PDF de factura |

### Billing Info & Usage

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/billing-info` | GET | Información de facturación del usuario |
| `/payments/billing-info` | PUT | Actualizar dirección de facturación |
| `/payments/usage` | GET | Estadísticas de uso del plan actual |

### Wallet

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/wallet` | GET | Balance y estado de wallet |
| `/payments/wallet/transactions` | GET | Historial de transacciones de wallet (paginado) |
| `/payments/wallet/deposit` | POST | Depositar fondos a wallet |
| `/payments/wallet/withdraw` | POST | Retirar fondos de wallet |

### Coupons & Summary

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/payments/coupons/validate` | POST | Validar código de cupón |
| `/payments/billing-summary` | GET | Resumen completo de billing (todos los datos) |

## Uso Rápido

```tsx
import { Pricing, Billing } from '@/modules/payments';
import { usePaymentStore } from '@/stores/paymentStore';

// Uso en router
<Route path="/pricing" element={<Pricing />} />
<Route path="/billing" element={<Billing />} />

// Uso de store
function MyComponent() {
  const {
    currentSubscription,
    plans,
    wallet,
    fetchPlans,
    createCheckoutSession,
    depositToWallet
  } = usePaymentStore();

  useEffect(() => {
    fetchPlans();
  }, []);

  const handleSubscribe = async (planSlug: string) => {
    const session = await createCheckoutSession(planSlug, 'monthly');
    // Redirect to Stripe Checkout
    window.location.href = session.url;
  };

  const handleDeposit = async () => {
    await depositToWallet(100, 'pm_card_visa');
  };

  return (
    <div>
      <p>Current Plan: {currentSubscription?.plan.name}</p>
      <p>Wallet Balance: ${wallet?.balance}</p>
      <button onClick={() => handleSubscribe('pro')}>Upgrade to Pro</button>
      <button onClick={handleDeposit}>Deposit $100</button>
    </div>
  );
}
```

## Características Principales

### Plan Management
- 5 tiers: Free, Basic, Pro, Premium, Enterprise
- Billing intervals: Monthly y Yearly
- Feature comparison matrix
- Popular badge for recommended plan
- Trial periods support

### Subscription Lifecycle
- Stripe Checkout integration
- Instant upgrade/downgrade con prorrateado
- Cancel immediately o al final del período
- Reactivación de suscripciones canceladas
- Billing portal de Stripe para self-service

### Payment Methods
- Add/remove tarjetas de crédito
- Set default payment method
- Stripe Elements para PCI compliance
- Soporte para múltiples métodos

### Invoicing
- Generación automática de invoices
- Download PDF de facturas
- Email notifications
- Payment status tracking
- Line items detallados

### Wallet System
- Internal balance para deposits/withdrawals
- Transaction history con tipos (deposit, withdrawal, transfer, fee, refund)
- Multiple wallet types: trading, investment, earnings, referral
- Status management: active, frozen, closed

### Usage Tracking
- API calls limit
- Courses enrollment limit
- Paper trades limit
- Watchlist symbols limit
- Real-time progress bars con warnings

### Coupons & Discounts
- Percentage y amount off
- Duration: once, forever, repeating
- Code validation
- Auto-apply en checkout

## Tests

```bash
# Tests unitarios del módulo
npm run test modules/payments

# Tests de integración con Stripe
npm run test:integration payments/stripe

# Tests E2E de flujos de pago
npm run test:e2e payments
```

## Roadmap

### Pendientes - Alta Prioridad (P0)
- [ ] **PCI-DSS Full Compliance** (80h) - BLOCKER LEGAL - Auditoría completa de compliance
- [ ] **SCA (Strong Customer Authentication)** (40h) - 3D Secure 2.0 obligatorio en EU

### Mediano Plazo (P1-P2)
- [ ] **Crypto Payments** (60h) - Bitcoin, Ethereum, USDT via CoinPayments
- [ ] **Invoice Customization** (15h) - Templates personalizables de invoices
- [ ] **Refund Management** (25h) - Sistema de reembolsos con workflow
- [ ] **Tax Calculation** (40h) - Integración con TaxJar/Avalara

### Largo Plazo (P3)
- [ ] **Multi-currency Support** (50h) - Precios en USD, EUR, GBP
- [ ] **Enterprise Contracts** (60h) - Contratos anuales con invoicing manual
- [ ] **Affiliate System** (80h) - Programa de afiliados con comisiones

## Dependencias

- `@stripe/stripe-js` - Stripe.js library
- `@stripe/react-stripe-js` - React components para Stripe
- `zustand` - State management
- `axios` - HTTP client
- `lucide-react` - Icons

## Documentación Relacionada

- **ET Specs:** No aplica (funcionalidad base)
- **User Stories:** US-PAY-001 a US-PAY-015
- **Backend API Docs:** `/docs/api/payments.md`
- **Stripe Integration Guide:** `/docs/integrations/stripe.md`
- **PCI Compliance:** `/docs/security/pci-dss.md`

---

**Última actualización:** 2026-01-25
**Autor:** Claude Opus 4.5
