---
id: "MAP-OQI-005-payments-stripe"
title: "Mapa de OQI-005-payments-stripe"
type: "Index"
project: "trading-platform"
updated_date: "2026-01-04"
---

# _MAP: OQI-005 - Pagos y Stripe

**Última actualización:** 2025-12-05
**Estado:** Parcialmente Implementado
**Versión:** 1.0.0

---

## Propósito

Esta épica implementa el sistema completo de pagos integrado con Stripe, incluyendo suscripciones (Free, Basic, Pro, Premium), compra de cursos, wallet interno, depósitos para inversión y facturación automática.

---

## Contenido del Directorio

```
OQI-005-payments-stripe/
├── README.md                    # Documentación técnica existente
├── _MAP.md                      # Este archivo - índice
├── requerimientos/              # Documentos de requerimientos funcionales
│   ├── RF-PAY-001-suscripciones.md   # Planes de suscripción
│   ├── RF-PAY-002-checkout.md        # Checkout y pagos
│   ├── RF-PAY-003-wallet.md          # Wallet interno
│   ├── RF-PAY-004-facturacion.md     # Facturación automática
│   ├── RF-PAY-005-webhooks.md        # Webhooks de Stripe
│   └── RF-PAY-006-reembolsos.md      # Sistema de reembolsos
├── especificaciones/            # Especificaciones técnicas
│   ├── ET-PAY-001-database.md   # Modelo de datos
│   ├── ET-PAY-002-stripe-api.md # Integración Stripe
│   ├── ET-PAY-003-webhooks.md   # Manejo de webhooks
│   ├── ET-PAY-004-api.md        # Endpoints REST
│   ├── ET-PAY-005-frontend.md   # Componentes React
│   └── ET-PAY-006-security.md   # Seguridad PCI DSS
├── historias-usuario/           # User Stories
│   ├── US-PAY-001-ver-planes.md
│   ├── US-PAY-002-suscribirse.md
│   ├── US-PAY-003-cambiar-plan.md
│   ├── US-PAY-004-cancelar-suscripcion.md
│   ├── US-PAY-005-comprar-curso.md
│   ├── US-PAY-006-agregar-metodo-pago.md
│   ├── US-PAY-007-ver-facturas.md
│   ├── US-PAY-008-depositar-wallet.md
│   ├── US-PAY-009-retirar-wallet.md
│   ├── US-PAY-010-ver-historial.md
│   ├── US-PAY-011-solicitar-reembolso.md
│   └── US-PAY-012-actualizar-tarjeta.md
└── implementacion/              # Trazabilidad de implementación
    └── TRACEABILITY.yml
```

---

## Requerimientos Funcionales

| ID | Nombre | Prioridad | SP | Estado |
|----|--------|-----------|-----|--------|
| RF-PAY-001 | Planes de Suscripción | P0 | 8 | ✅ Implementado |
| RF-PAY-002 | Checkout y Pagos | P0 | 8 | ✅ Implementado |
| RF-PAY-003 | Wallet Interno | P1 | 8 | Pendiente |
| RF-PAY-004 | Facturación Automática | P1 | 5 | Pendiente |
| RF-PAY-005 | Webhooks Stripe | P0 | 5 | ✅ Implementado |
| RF-PAY-006 | Sistema de Reembolsos | P2 | 6 | Pendiente |

**Total:** 40 SP

---

## Especificaciones Técnicas

| ID | Nombre | Componente | Estado |
|----|--------|------------|--------|
| ET-PAY-001 | Database | Database | ✅ Schema existe |
| ET-PAY-002 | Stripe API | Backend | ✅ Implementado |
| ET-PAY-003 | Webhooks | Backend | ✅ Implementado |
| ET-PAY-004 | API REST | Backend | ✅ Parcial |
| ET-PAY-005 | Frontend | Frontend | Pendiente |
| ET-PAY-006 | Security | Backend | ✅ Implementado |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-PAY-001 | Ver planes de suscripción | P0 | 2 | Pendiente |
| US-PAY-002 | Suscribirse a un plan | P0 | 5 | ✅ Backend listo |
| US-PAY-003 | Cambiar plan de suscripción | P1 | 3 | Pendiente |
| US-PAY-004 | Cancelar suscripción | P1 | 3 | Pendiente |
| US-PAY-005 | Comprar curso individual | P1 | 3 | ✅ Backend listo |
| US-PAY-006 | Agregar método de pago | P0 | 3 | Pendiente |
| US-PAY-007 | Ver historial de facturas | P1 | 3 | Pendiente |
| US-PAY-008 | Depositar en wallet | P1 | 5 | Pendiente |
| US-PAY-009 | Retirar de wallet | P2 | 5 | Pendiente |
| US-PAY-010 | Ver historial de transacciones | P1 | 2 | Pendiente |
| US-PAY-011 | Solicitar reembolso | P2 | 3 | Pendiente |
| US-PAY-012 | Actualizar tarjeta | P1 | 3 | Pendiente |

**Total:** 40 SP

---

## Planes de Suscripción

| Plan | Precio | Stripe Price ID | Features |
|------|--------|-----------------|----------|
| **Free** | $0/mes | - | Paper trading, cursos básicos, 3 señales/día |
| **Basic** | $19/mes | `price_1Sb3k64dPtEGmLmpeAdxvmIu` | Trading real, 10 señales/día, 1 agente |
| **Pro** | $49/mes | `price_1Sb3k64dPtEGmLmpm5n5bbJH` | Señales ilimitadas, 3 agentes, soporte prioritario |
| **Premium** | $99/mes | `price_1Sb3k74dPtEGmLmpHfLpUkvQ` | API access, white label, soporte dedicado |

---

## Dependencias

### Depende de:

- **OQI-001:** Autenticación (usuarios) - ✅ Completado

### Bloquea:

- **OQI-002:** Education (compra de cursos premium)
- **OQI-004:** Investment (depósitos)

---

## Stack Técnico

| Capa | Tecnología | Uso |
|------|------------|-----|
| Frontend | React + Stripe Elements | UI de pagos |
| Backend | Express.js + Stripe SDK | API |
| Database | PostgreSQL | Transacciones |
| Payments | Stripe | Procesamiento |

---

## Webhooks Configurados

| Evento | Acción |
|--------|--------|
| `payment_intent.succeeded` | Actualizar pago, otorgar acceso |
| `payment_intent.payment_failed` | Notificar usuario, marcar fallido |
| `customer.subscription.created` | Activar suscripción |
| `customer.subscription.updated` | Sincronizar estado |
| `customer.subscription.deleted` | Cancelar acceso |
| `invoice.paid` | Registrar factura pagada |
| `invoice.payment_failed` | Notificar problema de pago |

---

## Seguridad

### PCI DSS Compliance
- Nunca almacenar números de tarjeta
- Usar Stripe Elements (tokenización)
- Validar webhook signatures
- HTTPS obligatorio

### Rate Limiting
| Endpoint | Límite |
|----------|--------|
| `/payments/*` | 20/hora |
| `/webhooks` | Ilimitado (validación Stripe) |

---

## Criterios de Aceptación

### Funcionales

- [ ] Usuarios pueden ver y comparar planes
- [ ] Checkout con Stripe Elements funciona
- [ ] Suscripciones se activan automáticamente
- [ ] Webhooks procesan todos los eventos
- [ ] Facturas disponibles para descarga
- [ ] Wallet permite depósitos y retiros

### No Funcionales

- [ ] Checkout carga en < 2 segundos
- [ ] 99.9% uptime en procesamiento de pagos
- [ ] Transacciones atómicas

### Técnicos

- [ ] Cobertura de tests > 80%
- [ ] Logs de auditoría para pagos
- [ ] Modo test/producción separados

---

## Hitos

| Hito | Entregables | Target |
|------|-------------|--------|
| M1 | Planes + checkout básico | Sprint 5 ✅ |
| M2 | Suscripciones completas | Sprint 5 |
| M3 | Wallet + facturación | Sprint 6 |
| M4 | Reembolsos + polish | Sprint 6 |

---

## Referencias

- [README Técnico](./README.md)
- [Stripe Dashboard](https://dashboard.stripe.com)
- [Vision del Producto](../../00-vision-general/VISION-PRODUCTO.md)
- [_MAP Fase MVP](../_MAP.md)