Payments API — Invoicing and Payments in PortalHub - PortalHub

The Payments API manages the pagos_facturacion table, which tracks monetary transactions between clients and the consultancy. Each payment record links a client, an optional accounting service (servicios_contables), a monetary amount, and two independent status fields: estado_pago (the payment collection status) and estado_factura (the invoicing status). Clients can view their own payment history. Administrators and Asesors can see all payments and update statuses. Only authenticated users with the correct role can register new payments.

Payment and invoice status reference

`estado_pago`	`estado_factura`	Description
`Pendiente`	`Pendiente`	Payment has been registered but not yet processed or confirmed. Default state on creation.
`Pagado`	`Pendiente`	Payment confirmed as received. `fecha_pago` is set automatically to `NOW()`. Invoice not yet issued.
`Pagado`	`Emitida`	Payment confirmed and invoice issued to the client.
`Cancelado`	`Pendiente`	Payment was cancelled before collection.

estado_pago and estado_factura are independent fields. Updating estado_pago via actualizar_estado.php does not automatically change estado_factura. Manage each field separately if your workflow requires coordinating both.

The estado_pago ENUM values enforced at runtime by actualizar_estado.php are Pendiente, Pagado, and Cancelado. The schema.sql file defines this column as ENUM('Pendiente','Registrado','Aprobado'), which does not match the PHP validation logic. The values documented here reflect what the PHP application code accepts and validates. Align the database schema with the application code before deploying to production.

GET /backend/modules/pagos/listar.php

Return all payment records visible to the authenticated user, ordered by id_pago DESC. The response includes joined fields from servicios_contables and cat_servicios for service context. Authentication: Any authenticated user (checkAuth)

Caller role	Records returned
`ROL_ADMIN` (`1`)	All payments in the system
`ROL_ASESOR` (`2`)	All payments in the system
`ROL_CLIENTE` (`3`)	Only payments where `id_cliente = session user`

Request

No parameters required.

curl -X GET https://your-domain.com/backend/modules/pagos/listar.php \
  -H "Cookie: PHPSESSID=<your_session_id>"

id_pago

integer

Auto-incremented primary key for the payment record.

id_cliente

integer

id_usuario of the client associated with this payment.

id_servicio

integer | null

Foreign key to servicios_contables. May be null if the payment is not tied to a specific service instance.

monto

decimal

Payment amount with two decimal places (e.g., "2500.00").

estado_pago

enum

Collection status: Pendiente, Pagado, or Cancelado.

estado_factura

enum

Invoice status: Pendiente or Emitida.

fecha_pago

datetime | null

Date and time the payment was confirmed. Set automatically when estado_pago is updated to "Pagado". null until that transition occurs.

estado_servicio

enum | null

Service status from servicios_contables: Pendiente, En proceso, or Completado. null if no service is linked.

nombre_servicio

string | null

Human-readable service name from cat_servicios. null if no service is linked.

Error responses

HTTP	Message
`401`	No autorizado. Inicie sesión Primero.
`500`	Error en la consulta

POST /backend/modules/pagos/registrar.php

Create a new payment record with an initial estado_pago of "Pendiente". The referenced id_servicio must exist in servicios_contables. The monto must be a positive numeric value. Authentication: Any authenticated user (checkAuth)

Pass id_servicio whenever the payment corresponds to a specific accounting service instance. If the payment is standalone (e.g., a consulting retainer), omit id_servicio — though the current source requires it; see warning below.

The current implementation of registrar.php validates that id_servicio is not empty (!$id_servicio) and returns HTTP 400 if it is absent. While the schema declares id_servicio as nullable, the endpoint treats it as required. Always supply a valid id_servicio.

Request body

id_cliente

integer

required

The id_usuario of the client for whom the payment is being registered.

id_servicio

integer

required

A valid id_servicio from the servicios_contables table. The server verifies existence before inserting.

monto

number

required

The payment amount. Must be a positive numeric value. Stored as DECIMAL(10,2).

curl -X POST https://your-domain.com/backend/modules/pagos/registrar.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_cliente": 7,
    "id_servicio": 3,
    "monto": 2500.00
  }'

id_pago

integer

The auto-incremented ID of the newly created payment record.

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`400`	Monto no válido
`401`	No autorizado. Inicie sesión Primero.
`404`	Servicio no encontrado
`405`	Método no permitido
`500`	Error al registrar pago

GET /backend/modules/pagos/detalle.php

Retrieve the full detail of a single payment record, including joined service and service-type information. Clients can only view their own payments; attempting to access another client’s payment returns HTTP 403. Authentication: Any authenticated user (checkAuth)

Query parameters

id_pago

integer

required

The ID of the payment record to retrieve.

curl -X GET "https://your-domain.com/backend/modules/pagos/detalle.php?id_pago=5" \
  -H "Cookie: PHPSESSID=<your_session_id>"

id_pago

integer

Primary key of the payment.

id_cliente

integer

id_usuario of the client associated with this payment.

id_servicio

integer | null

Foreign key to servicios_contables, if applicable.

monto

decimal

Payment amount with two decimal places.

estado_pago

enum

Current collection status: Pendiente, Pagado, or Cancelado.

estado_factura

enum

Current invoice status: Pendiente or Emitida.

fecha_pago

datetime | null

Timestamp when the payment was confirmed. null until estado_pago transitions to "Pagado".

estado_servicio

enum | null

Status of the linked service from servicios_contables.

nombre_servicio

string | null

Service name from cat_servicios.

Access control

detalle.php reads the role from $_SESSION['rol'], but the login endpoint sets only $_SESSION['id_rol']. Because $_SESSION['rol'] is never populated, the ROL_CLIENTE ownership check never triggers, and any authenticated user can view any payment record at runtime. The intended restriction for clients is listed below for reference.

Session role	Intended access	Actual runtime behaviour
`ROL_ADMIN` (`1`)	Any payment	Any payment
`ROL_ASESOR` (`2`)	Any payment	Any payment
`ROL_CLIENTE` (`3`)	Only where `id_cliente = session user`	Any payment

Error responses

HTTP	Message
`400`	ID de pago no proporcionado
`401`	No autorizado. Inicie sesión Primero.
`403`	No tiene permisos para ver este pago
`404`	Pago no encontrado
`405`	Método no permitido
`500`	Error al obtener detalle de pago

POST /backend/modules/pagos/actualizar_estado.php

Update the estado_pago of a payment record. When estado_pago is set to "Pagado", the server automatically records fecha_pago = NOW() in the same UPDATE statement. Required role: Admin (1) or Asesor (2)

This endpoint updates only estado_pago. If you also need to update estado_factura (e.g., mark an invoice as issued), you must extend this endpoint or handle that update at the database level — the current implementation does not expose estado_factura as a writable field through this endpoint.

Request body

id_pago

integer

required

The ID of the payment record to update.

estado_pago

string

required

The new payment status. Must be one of: "Pendiente", "Pagado", or "Cancelado". Any other value returns HTTP 400.

curl -X POST https://your-domain.com/backend/modules/pagos/actualizar_estado.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_pago": 5,
    "estado_pago": "Pagado"
  }'

Automatic `fecha_pago` behaviour

When estado_pago is set to "Pagado", the SQL executed is:

UPDATE pagos_facturacion
SET estado_pago = 'Pagado', fecha_pago = NOW()
WHERE id_pago = ?

For "Pendiente" or "Cancelado", fecha_pago is left unchanged.

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`400`	Estado de pago no válido
`401`	No autorizado. Inicie sesión Primero.
`403`	Acceso denegado. Permisos insuficientes.
`404`	Pago no encontrado
`405`	Método no permitido
`500`	Error al actualizar estado de pago

Overview

Endpoints

Payments API — Invoicing and Payments in PortalHub

Payment and invoice status reference

GET /backend/modules/pagos/listar.php

Request

Error responses

POST /backend/modules/pagos/registrar.php

Request body

Error responses

GET /backend/modules/pagos/detalle.php

Query parameters

Access control

Error responses

POST /backend/modules/pagos/actualizar_estado.php

Request body

Automatic `fecha_pago` behaviour

Error responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Payment and invoice status reference

​GET /backend/modules/pagos/listar.php

​Request

​Error responses

​POST /backend/modules/pagos/registrar.php

​Request body

​Error responses

​GET /backend/modules/pagos/detalle.php

​Query parameters

​Access control

​Error responses

​POST /backend/modules/pagos/actualizar_estado.php

​Request body

​Automatic fecha_pago behaviour

​Error responses

Build docs developers (and LLMs) love

Payment and invoice status reference

GET /backend/modules/pagos/listar.php

Request

Error responses

POST /backend/modules/pagos/registrar.php

Request body

Error responses

GET /backend/modules/pagos/detalle.php

Query parameters

Access control

Error responses

POST /backend/modules/pagos/actualizar_estado.php

Request body

Automatic `fecha_pago` behaviour

Error responses