--- id: "US-PAY-010" title: "Ver Historial de Pagos y Transacciones" 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-010: Ver Historial de Pagos y Transacciones **Version:** 1.0.0 **Fecha:** 2025-12-05 **Estado:** ✅ Implementado **Story Points:** 2 **Prioridad:** P1 (Alta) **Épica:** [OQI-005](../_MAP.md) --- ## Historia de Usuario **Como** usuario de Trading Platform con actividad de pagos **Quiero** ver un historial completo de mis transacciones **Para** rastrear mis gastos, recargas de wallet y compras realizadas --- ## Criterios de Aceptación ### AC-001: Acceder a Historial de Pagos **Dado** que soy usuario logueado **Cuando** navego a "Configuración → Historial de Pagos" **Entonces** debería ver: - Lista de todas mis transacciones ordenadas por fecha (más reciente primero) - Para cada transacción: - Fecha y hora - Tipo (Suscripción, Curso, Recarga de Wallet, Reembolso) - Descripción detallada - Monto con signo (+ para créditos, - para débitos) - Estado (Exitoso, Fallido, Pendiente, Reembolsado) - Método de pago usado - Link a factura (si aplica) - Paginación si tengo > 20 transacciones ### AC-002: Ver Sin Transacciones **Dado** que soy usuario nuevo sin actividad de pagos **Cuando** navego al historial de pagos **Entonces** debería ver: - Mensaje: "No tienes transacciones todavía" - Ilustración o ícono de historial vacío - Botón "Explorar Cursos" o "Ver Planes" ### AC-003: Tipos de Transacciones Mostradas **Dado** que estoy viendo mi historial **Cuando** reviso las transacciones **Entonces** debería ver claramente diferenciados: **Suscripciones:** - ícono 🔄 - "Pago de suscripción Pro - Diciembre 2025" - Monto: -$49.00 - Estado: Exitoso **Cursos:** - ícono 📚 - "Compra de curso: Trading Básico 101" - Monto: -$29.00 - Estado: Exitoso **Recarga de Wallet:** - ícono 💰 - "Recarga de wallet" - Monto: +$50.00 - Estado: Exitoso **Reembolsos:** - ícono ↩️ - "Reembolso: Curso Trading Avanzado" - Monto: +$49.00 - Estado: Reembolsado **Débitos de Wallet:** - ícono 📤 - "Pago con wallet: Curso React Avanzado" - Monto: -$29.00 - Estado: Exitoso ### AC-004: Filtrar por Tipo **Dado** que tengo múltiples tipos de transacciones **Cuando** aplico filtro de tipo **Entonces** debería poder filtrar por: - Todos (por defecto) - Suscripciones - Cursos - Wallet (recargas y débitos) - Reembolsos - Solo exitosos - Solo fallidos ### AC-005: Filtrar por Fecha **Dado** que quiero ver transacciones de un período específico **Cuando** selecciono rango de fechas **Entonces** debería: - Ver selector de fecha (desde - hasta) - Opciones rápidas: "Último mes", "Últimos 3 meses", "Este año", "Todo" - Actualizar lista con transacciones del rango seleccionado ### AC-006: Ver Detalles de Transacción **Dado** que quiero ver más información de una transacción **Cuando** hago click en una transacción **Entonces** debería ver modal/expandir con: - Todos los detalles de la transacción - ID de transacción (Stripe Payment Intent ID) - Método de pago (Visa •••• 4242, Wallet, etc.) - Fecha y hora exacta - Estado detallado - Link a factura (si existe) - Link a recurso comprado (curso, suscripción) - Botón "Solicitar Reembolso" (si es elegible) ### AC-007: Transacciones Fallidas **Dado** que tengo transacciones fallidas **Cuando** las veo en el historial **Entonces** debería: - Ver badge rojo "Fallido" - Ver motivo del fallo: "Tarjeta rechazada", "Fondos insuficientes", etc. - Ver botón "Reintentar" (si aplica) - NO ver factura ni acceso a recurso ### AC-008: Exportar Historial **Dado** que quiero guardar mi historial para registros **Cuando** hago click en "Exportar" **Entonces** debería: - Ver opciones: CSV, PDF - Seleccionar rango de fechas - Descargar archivo con formato: - CSV: Fecha, Tipo, Descripción, Monto, Estado, Método - PDF: Documento formateado con logo y tabla ### AC-009: Balance Actual de Wallet **Dado** que tengo wallet con saldo **Cuando** veo el historial de pagos **Entonces** debería ver: - Card destacado en la parte superior: - "Balance de Wallet: $50.00" - Botón "Recargar" - Link "Ver transacciones de wallet" - Historial de transacciones de wallet integrado en lista general ### AC-010: Buscar Transacción **Dado** que estoy buscando una transacción específica **Cuando** uso el buscador **Entonces** debería poder buscar por: - Descripción (nombre de curso, tipo de pago) - Monto (ej: "49" muestra todos de $49) - ID de transacción - Resultados se filtran en tiempo real ### AC-011: Solicitar Reembolso desde Historial **Dado** que veo una compra elegible para reembolso **Cuando** hago click en "Solicitar Reembolso" **Entonces** debería: - Ver formulario de solicitud con: - Motivo (lista predefinida) - Comentarios adicionales (opcional) - Enviar solicitud - Ver confirmación: "Solicitud de reembolso enviada" - Ver estado actualizado: "Reembolso Pendiente" --- ## Mockup ``` ┌─────────────────────────────────────────────────────────────┐ │ │ │ Historial de Pagos │ │ │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 💰 Balance de Wallet: $50.00 │ │ │ │ [Recargar] [Ver transacciones de wallet] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ Filtros: [Todos ▼] [Último mes ▼] [Buscar...] │ │ [Exportar] │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 🔄 Pago de suscripción Pro - Diciembre 2025 │ │ │ │ 05/12/2025 14:30 [Exitoso] │ │ │ │ Visa •••• 4242 │ │ │ │ -$49.00 │ │ │ │ [Ver Factura] [Ver Detalles] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 💰 Recarga de wallet │ │ │ │ 01/12/2025 10:15 [Exitoso] │ │ │ │ Visa •••• 4242 │ │ │ │ +$50.00 │ │ │ │ [Ver Factura] [Ver Detalles] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 📚 Compra de curso: Trading Básico 101 │ │ │ │ 28/11/2025 16:45 [Exitoso] │ │ │ │ Wallet │ │ │ │ -$29.00 │ │ │ │ [Ver Factura] [Ir al Curso] [Solicitar │ │ │ │ Reembolso] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ ❌ Pago de suscripción Pro - Noviembre 2025 │ │ │ │ 05/11/2025 14:30 [Fallido] │ │ │ │ Visa •••• 5555 │ │ │ │ Motivo: Tarjeta rechazada -$49.00 │ │ │ │ [Reintentar] [Actualizar Tarjeta] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ ↩️ Reembolso: Curso Trading Avanzado │ │ │ │ 15/10/2025 09:20 [Reembolsado] │ │ │ │ Visa •••• 4242 │ │ │ │ +$49.00 │ │ │ │ [Ver Nota de Crédito] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ Mostrando 1-10 de 47 transacciones │ │ [← Anterior] [1] [2] [3] [4] [5] [Siguiente →] │ │ │ └─────────────────────────────────────────────────────────────┘ ───────────── Modal: Detalles de Transacción ───────────── ┌─────────────────────────────────────────────────────────────┐ │ [X] │ │ Detalles de Transacción │ │ │ │ Tipo: Compra de Curso │ │ Descripción: Trading Básico 101 │ │ Fecha: 28/11/2025 16:45:23 │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ Monto: $29.00 USD │ │ Método de pago: Wallet │ │ Estado: Exitoso ✅ │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ ID de transacción: │ │ wt_3Abc123def456ghi789 │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ [Ver Factura] [Ir al Curso] [Solicitar Reembolso] │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Flujo de Usuario (Gherkin) ```gherkin Feature: Ver Historial de Pagos Scenario: Ver historial completo Given que soy usuario logueado "juan@example.com" And he realizado 5 transacciones en el último mes When navego a "Configuración → Historial de Pagos" Then debería ver 5 transacciones listadas And deberían estar ordenadas por fecha descendente And debería ver mi balance de wallet en la parte superior Scenario: Filtrar por tipo de transacción Given que estoy viendo mi historial de pagos And tengo transacciones de suscripciones y cursos When selecciono filtro "Cursos" Then debería ver solo transacciones de compra de cursos And NO debería ver transacciones de suscripciones Scenario: Ver detalles de transacción exitosa Given que estoy viendo mi historial When hago click en transacción "Curso Trading Básico 101" Then debería ver modal con detalles completos And debería ver ID de transacción And debería ver método de pago usado And debería ver botón "Ver Factura" And debería ver botón "Ir al Curso" Scenario: Solicitar reembolso desde historial Given que compré curso hace 3 días con 0% de progreso When veo esa transacción en el historial And hago click en "Solicitar Reembolso" Then debería ver formulario de solicitud When selecciono motivo "No es lo que esperaba" And confirmo solicitud Then debería ver "Solicitud de reembolso enviada" And estado debería cambiar a "Reembolso Pendiente" Scenario: Exportar historial a CSV Given que tengo 20 transacciones When hago click en "Exportar" And selecciono "CSV" And selecciono "Últimos 3 meses" Then debería descargar archivo "Trading Platform_Historial_2025.csv" And archivo debería contener todas las transacciones del período Scenario: Usuario sin transacciones Given que soy usuario nuevo sin actividad When navego a "Historial de Pagos" Then debería ver "No tienes transacciones todavía" And debería ver botón "Explorar Cursos" ``` --- ## Notas Técnicas ### Frontend - Componente: `apps/frontend/src/pages/Settings/PaymentHistory.tsx` - Modal: `TransactionDetailsModal.tsx` - Fetch: `GET /api/v1/payments/history` - Integrar con wallet balance: `GET /api/v1/wallet/balance` ### Backend **Endpoint Principal:** `GET /api/v1/payments/history` Query params: - `?type=subscription|course|wallet|refund` - `?status=succeeded|failed|refunded` - `?from=2025-01-01&to=2025-12-31` - `?search=trading` - `?page=1&limit=20` Response: ```json { "transactions": [ { "id": "uuid", "type": "subscription", "description": "Pago de suscripción Pro - Diciembre 2025", "amount": -49.00, "currency": "USD", "status": "succeeded", "paymentMethod": { "type": "card", "brand": "visa", "last4": "4242" }, "invoiceId": "uuid-factura", "resourceId": "uuid-subscription", "resourceType": "subscription", "refundable": false, "createdAt": "2025-12-05T14:30:00Z" } ], "walletBalance": 50.00, "total": 47, "page": 1, "perPage": 20 } ``` **Endpoint de Exportación:** `GET /api/v1/payments/history/export` Query params: - `?format=csv|pdf` - `?from=2025-01-01&to=2025-12-31` Response: Stream archivo CSV/PDF ### Database **Query combina múltiples tablas:** ```sql SELECT 'payment' as source, p.id, p.type, p.description, p.amount * -1 as amount, -- Débito p.status, p.created_at FROM billing.payments p WHERE p.user_id = :userId UNION ALL SELECT 'wallet_transaction' as source, wt.id, wt.type, wt.description, wt.amount, -- Puede ser + o - 'succeeded' as status, wt.created_at FROM billing.wallet_transactions wt WHERE wt.wallet_id = (SELECT id FROM billing.wallets WHERE user_id = :userId) UNION ALL SELECT 'refund' as source, r.id, 'refund' as type, 'Reembolso: ' || p.description, r.amount as amount, -- Positivo r.status, r.created_at FROM billing.refunds r JOIN billing.payments p ON r.payment_id = p.id WHERE r.user_id = :userId ORDER BY created_at DESC ``` ### Exportación CSV ```csv Fecha,Tipo,Descripción,Monto,Estado,Método 2025-12-05 14:30,Suscripción,Pago de suscripción Pro - Diciembre 2025,-$49.00,Exitoso,Visa 4242 2025-12-01 10:15,Recarga Wallet,Recarga de wallet,+$50.00,Exitoso,Visa 4242 2025-11-28 16:45,Curso,Compra: Trading Básico 101,-$29.00,Exitoso,Wallet ``` --- ## Dependencias - [RF-PAY-003: Sistema de Wallet](../requerimientos/RF-PAY-003-wallet.md) - [RF-PAY-006: Sistema de Reembolsos](../requerimientos/RF-PAY-006-reembolsos.md) --- ## Requerimientos Relacionados - [RF-PAY-003: Sistema de Wallet Interno](../requerimientos/RF-PAY-003-wallet.md) - [RF-PAY-004: Sistema de Facturación](../requerimientos/RF-PAY-004-facturacion.md) - [RF-PAY-006: Sistema de Reembolsos](../requerimientos/RF-PAY-006-reembolsos.md) --- ## Tareas Técnicas ### Frontend - [ ] Página `PaymentHistory.tsx` - [ ] Modal `TransactionDetailsModal.tsx` - [ ] Wallet balance card - [ ] Filtros (tipo, fecha, búsqueda) - [ ] Exportación (CSV/PDF) - [ ] Paginación - [ ] Indicador de reembolsabilidad ### Backend - [ ] Endpoint `GET /payments/history` - [ ] Combinar datos de payments + wallet_transactions + refunds - [ ] Implementar filtros y búsqueda - [ ] Endpoint `GET /payments/history/export` - [ ] Generar CSV/PDF - [ ] Optimizar query para performance ### Testing - [ ] Test: Usuario ve todas sus transacciones - [ ] Test: Filtros funcionan correctamente - [ ] Test: Búsqueda encuentra transacciones - [ ] Test: Exportación CSV genera archivo correcto - [ ] Test: Paginación funciona - [ ] Test: Balance de wallet se muestra correctamente - [ ] Test: No puede ver transacciones de otros usuarios