Módulo de Inscripciones y Pagos

Propósito

Este módulo está diseñado para gestionar el ciclo completo de pagos, reembolsos y notificaciones financieras dentro del sistema, proporcionando una experiencia fluida tanto para los clientes como para la administración.

Funcionalidades Clave

Pagos en Línea

  • Integración con Pasarelas de Pago: Soporte para múltiples pasarelas de pago (ej., PayU, Wompi, Nequi) para procesar transacciones de forma autogestionada por el cliente.

  • Flujo de Checkout: Permite a los usuarios completar pagos directamente desde la plataforma mediante redirección segura a las pasarelas.

  • Confirmación Automática: Actualización del estado de las reservas y servicios una vez que el pago es confirmado por la pasarela a través de webhooks.

Gestión de Reembolsos

  • Procesamiento de Devoluciones: Sistema robusto para gestionar y procesar devoluciones de dinero, siguiendo las políticas de cancelación definidas.

  • Actualización de Estado: Las devoluciones actualizan el estado de la reserva o servicio asociado, reflejando el reembolso realizado.

  • Integración con Pasarelas: Capacidad para iniciar reembolsos directamente desde el sistema a través de las APIs de las pasarelas de pago.

  • Registro de Auditoría: Registro detallado de cada reembolso, incluyendo monto, motivo y usuario que lo procesó.

Notificaciones de Pagos

  • Recordatorios Automáticos: Envío automático de notificaciones (email, push) a los clientes para recordar pagos pendientes o vencidos.

  • Configuración de Recordatorios: Permite configurar la frecuencia y el contenido de los recordatorios.

  • Tracking de Notificaciones: Sistema para evitar el envío de notificaciones duplicadas y asegurar que los mensajes lleguen de manera oportuna.

Reportes Financieros

  • Exportación de Datos: Funcionalidades para exportar reportes financieros a formatos comunes como Excel/CSV y PDF.

  • Visualización Avanzada: Herramientas de visualización con gráficos estadísticos y filtros avanzados para analizar ingresos por día, cancha, tipo de servicio, etc.

  • Tipos de Reportes: Generación de reportes específicos para Reservas, Pagos, Clientes, Canchas y Eventos, facilitando la toma de decisiones financieras.

Comprobantes

  • Generación de Comprobantes: Creación automática y envío por correo electrónico de comprobantes de pago detallados en formato PDF.

  • Captura de transferencia (reservas): Imagen del comprobante bancario o Nequi en payment.foto (S3/R2 privado); ver Pagos de reserva con comprobante. Distinto del PDF por email.

Aspectos Técnicos

API Endpoints de Pagos

Endpoints de Administración (/admin/payments)

  • GET /admin/payments: Obtiene la lista de pagos con filtros y paginación

  • GET /admin/payments/stats: Obtiene estadísticas agregadas de pagos

  • GET /admin/payments/:id: Obtiene un pago específico por ID

  • GET /admin/payments/transaction/:transaction_id: Obtiene un pago por transaction_id del gateway

  • POST /admin/payments: Crea un nuevo pago (útil para pagos manuales o sincronización)

  • PATCH /admin/payments/:id: Actualiza un pago existente (permite actualizar campos específicos)

  • DELETE /admin/payments/:id: Elimina un pago del sistema

Características importantes: * El campo status es un boolean: false = pendiente, true = completado * Los pagos se crean ya vinculados a reserva o inscripción; la validación operativa usa PATCH con status * Soporte para paginación con limit y offset * Filtros por search, status, y reservation_id * Ordenamiento automático: pendientes primero, luego por fecha descendente

Endpoints de Cuenta (/account/payments)

  • GET /account/payments: Obtiene el historial de pagos del usuario autenticado con paginación

  • GET /account/payments/:id: Obtiene un pago específico del usuario autenticado

  • POST /account/payments: Crea un nuevo pago asociado a una reserva del cliente autenticado

Características: * Solo devuelve pagos asociados a reservas del usuario autenticado * Incluye información adicional de la reserva: court_name, checking, checkout * El campo status es un boolean: false = pendiente, true = completado

Endpoints de Reservas de Cuenta (/account/bookings)

  • GET /account/bookings: Obtiene las reservas del usuario autenticado con información detallada de pagos

Características: * Solo devuelve reservas del usuario autenticado * Incluye información agregada de pagos: total_paid, total_amount, is_payment_complete, can_add_payment * Los pagos dentro de las reservas incluyen formato dual: * status: String ("pending" o "completed") para compatibilidad con frontend * statusBoolean: Boolean equivalente (false = pending, true = completed)

Webhooks

  • POST /webhooks/payment: Recibe notificaciones de pagos del gateway de pago

Flujo de webhook: 1. El gateway envía notificación al webhook 2. El sistema busca si existe un pago con ese transaction_id 3. Si no existe, el pago se crea en el contexto del flujo de reserva/inscripción con su reservation_id o enrollment_id 4. Si existe, actualiza el estado según corresponda

Modelo de Datos

Tabla payment: * id: ID único del pago (integer, PK) * reservation_id: ID de la reservación asociada (integer, nullable, FK a reservation) * payment_type_id: ID del tipo de pago (integer, nullable, FK a payment_type) * amount: Monto del pago (decimal) * transaction_id: ID de transacción del gateway (string, nullable) * gateway_response: Respuesta completa del gateway (text, nullable) * status: Estado del pago (boolean: false = pendiente, true = completado) * date: Fecha del pago (timestamp, default: CURRENT_TIMESTAMP) * description: Descripción del pago (string, nullable) * foto: Referencia interna al comprobante en S3/R2 (string, nullable). Subida con POST/PATCH multipart; descarga con GET …​/payment/{paymentId}/foto; quitar comprobante con DELETE …​/payment/{paymentId}/foto; al eliminar el pago (DELETE …​/payment/{paymentId}) también se borra del bucket si existe

Pagos de reserva con comprobante

Almacenamiento privado S3-compatible (AWS S3 o Cloudflare R2), servicio PaymentReceiptStorage (functions/services/payment-receipt-storage.js). El panel permite Subir, Ver y Eliminar comprobante en /booking/payment/:id.

  • POST /admin/booking/{bookingId}/payment: JSON (foto = null) o multipart con foto (JPEG/PNG/WebP, máx. 5 MB)

  • PATCH /admin/booking/{bookingId}/payment/{paymentId}: JSON o multipart con foto (añadir o reemplazar)

  • GET /admin/booking/{bookingId}/payment/{paymentId}/foto: descarga autorizada (proxy; Bearer + CSRF)

  • DELETE /admin/booking/{bookingId}/payment/{paymentId}: elimina el pago; si tiene comprobante, también DeleteObject en bucket

  • DELETE /admin/booking/{bookingId}/payment/{paymentId}/foto: DeleteObject en bucket + payment.foto = null

  • Migración: 089_payment_foto.sql

  • Variables: AWS_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, opcional AWS_ENDPOINT, AWS_USE_PATH_STYLE_ENDPOINT, AWS_PUBLIC_BASE_URL

Diagramas: Subida y Visualización. Detalle HTTP: Comprobantes de pago.

Seguridad

  • Autenticación: Todos los endpoints requieren autenticación mediante OAuth2 local IdP (Bearer token)

  • Autorización: Los endpoints de administración requieren permisos de administrador

  • Validación: Se valida que las reservaciones existan antes de asociar pagos

  • Sanitización: Los datos de entrada se validan y sanitizan antes de insertar en la base de datos

  • Cumplimiento: Cumplimiento con estándares de seguridad PCI para el manejo de transacciones financieras

Base de Datos

  • Tabla principal: payment

  • Relaciones:

  • payment.reservation_id → reservation.id (FK, nullable)

  • payment.payment_type_id → payment_type.id (FK, nullable)

  • Índices: Se recomienda tener índices en transaction_id, reservation_id, y status para optimizar consultas

Módulo de tickets (panel)

Ventas de paquetes de boletos y tirillas desde el panel (/tickets), API /admin/tickets/*.

Flujo operativo

  1. Catálogo de programas y paquetes (GET /admin/tickets/programs).

  2. Cotización (POST /admin/tickets/quote) con package_id y ticket_count.

  3. Emisión (POST /admin/tickets/sales): comprador, teléfonos, pago.

  4. Historial y detalle (GET /admin/tickets/sales, GET /admin/tickets/sales/{id}).

Tarifas de paquetes: panel Tarifas → Tarifas de Paquetes (PUT /admin/tickets/packages).

Relación con eventos PMV

Los participantes de un evento pueden vincularse por client_id o ticket_id (boleto de tirilla). Ver Módulo de Eventos y Referencia de API — Tickets.