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.
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 pueden ser "huérfanos" (sin reservation_id) cuando se reciben desde webhooks antes de crear la reserva
* 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, crea un pago huérfano
4. Si existe y tiene reservation_id, actualiza el estado
5. Si existe sin reservation_id, lo mantiene como huérfano hasta que se alinee
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)
Concepto de Pagos Huérfanos:
Los pagos huérfanos son aquellos que no tienen reservation_id asociado. Esto puede ocurrir cuando:
* Se recibe un webhook del gateway antes de que se cree la reserva
* Se crea un pago manualmente sin asociar a una reserva
* Se necesita registrar un pago que aún no está vinculado a una reserva específica
Los pagos huérfanos pueden ser asignados a una reserva posteriormente usando PATCH /admin/payments/:id.
Seguridad
-
Autenticación: Todos los endpoints requieren autenticación mediante Firebase Auth (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