Skip to main content
Payments are recorded against a transaction to track what has been collected. A transaction can receive multiple partial payments. When monto_pagado reaches monto_total (within a 0.01 tolerance), the transaction automatically transitions to cerrado — provided the kitchen status is also terminado.
Payments are also recorded in the associated caja_turno record automatically, incrementing either ventas_efectivo or ventas_qr.

​
POST /api/transacciones/:id/pagos

Registers a payment for the transaction. Authentication: Required Required role: Any authenticated user

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer <token>Yes
Content-Typeapplication/jsonYes

​
Path parameters

ParameterTypeDescription
idnumberThe transaction ID

​
Body

​
metodo_pago
string
required
Payment method. Must be efectivo or qr.
​
monto
number
required
Amount to apply to this payment. Must be ≥ 0.01 and cannot exceed the current monto_pendiente.
​
monto_recibido
number
Cash received from the customer. Required when metodo_pago is efectivo. Must be ≥ monto.
​
referencia_qr
string
QR transaction reference code. Recommended when metodo_pago is qr.

​
Response

​
Success (201)

​
id
number
Auto-generated payment ID.
​
transaccion_id
number
Parent transaction ID.
​
metodo_pago
string
Payment method used (efectivo or qr).
​
monto
string
Payment amount as a decimal string.
​
monto_recibido
string | null
Cash received, for efectivo payments.
​
referencia_qr
string | null
QR reference code, for qr payments.
​
cambio
string
Change to return to the customer (monto_recibido - monto). Always "0.00" for QR payments.
​
usuario_id
string
ID of the user who registered the payment.
​
creado_en
string
Payment timestamp.

​
Error responses

StatusDescription
400Transaction already fully paid
400monto exceeds monto_pendiente
400monto_recibido missing or less than monto when using efectivo
401Unauthorized
404Transaction not found

​
GET /api/transacciones/:id/pagos

Returns all active payments for the specified transaction. Authentication: Required Required role: Any authenticated user

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer <token>Yes

​
Path parameters

ParameterTypeDescription
idnumberThe transaction ID

​
Response

​
Success (200)

An array of payment objects (same shape as the POST response minus cambio).

​
Example — cash payment

curl -X POST http://localhost:3000/api/transacciones/42/pagos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metodo_pago": "efectivo", "monto": 85.00, "monto_recibido": 100.00}'

{
  "id": 5,
  "transaccion_id": 42,
  "metodo_pago": "efectivo",
  "monto": "85.00",
  "monto_recibido": "100.00",
  "referencia_qr": null,
  "cambio": "15.00",
  "usuario_id": "usr_1234567890",
  "creado_en": "2026-03-18T15:00:00.000Z",
  "actualizado_en": "2026-03-18T15:00:00.000Z",
  "borrado_en": null
}

​
Example — QR payment

curl -X POST http://localhost:3000/api/transacciones/42/pagos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metodo_pago": "qr", "monto": 85.00, "referencia_qr": "QR-123456789"}'

# List payments for transaction 42
curl http://localhost:3000/api/transacciones/42/pagos \
  -H "Authorization: Bearer $TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us