Registrar pago de compra
POST /api/purchases/{purchase_id}/payments
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra un pago (total o parcial). El dinero entra/sale del destino indicado (caja o cuenta) y queda en el libro de caja y bancos.
Quién puede usarlo: cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde 403.
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
date_of_payment |
date | Sí | Fecha del pago YYYY-MM-DD. |
payment_method_type_id |
string | Sí | Método de pago (01 efectivo, 04 transferencia...). |
payment_destination_id |
string/integer | Sí | cash o id de cuenta bancaria/billetera. |
payment |
numeric | Sí | Monto, mayor que 0. |
reference |
string | No | Referencia: número de operación, voucher, etc. |
has_card |
boolean | No | true si fue con tarjeta. |
card_brand_id |
string | No | Marca de tarjeta: 01 Visa, 02 Mastercard... |
Métodos de pago (payment_method_type_id): catálogo de la empresa. Los estándar son 01 Efectivo, 02 Tarjeta de crédito, 03 Tarjeta de débito, 04 Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con GET /api/finances/tables (data.payment_method_types).
Destino (payment_destination_id): cash = la caja abierta del usuario autenticado, o el id de una cuenta bancaria / billetera (ver 5. Cuentas bancarias o data.payment_destinations de GET /api/finances/tables).
Responde 409 cuando una regla de caja lo impide, por ejemplo:
- destino
cashy el usuario no tiene una caja abierta; - el método de pago no está habilitado para ese tipo de operación o destino;
- el pago pertenece a una caja ya cerrada (al eliminar);
- el mismo pago (mismo monto y método) se registró hace menos de 20 segundos (protección contra doble envío);
- el registro está anulado.
El mensaje (message) explica la causa y puede mostrarse al usuario tal cual.
Otros errores: 422 si falta un campo o payment ≤ 0; 404 si el registro no existe; 403 si es de otro vendedor.
La respuesta trae el pago creado (data.payment) y el resumen actualizado (data.summary). summary trae total (total del registro), total_paid (suma de pagos) y total_difference (saldo pendiente).
Parámetros
| Parámetro | Dónde | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
purchase_id |
ruta | sí | 1 |
Cuerpo
Content-Type: application/json
{
"date_of_payment": "2026-11-07",
"payment_method_type_id": "04",
"payment_destination_id": 3,
"payment": 20.0,
"reference": "OP-458721",
"has_card": false,
"card_brand_id": null
}
Respuestas
201 — Pago registrado
{
"success": true,
"data": {
"payment": {
"id": 31,
"date_of_payment": "2026-11-07",
"payment_method_type_id": "04",
"payment_method_type_description": "Transferencia",
"destination_type": "BankAccount",
"destination_id": 3,
"destination_description": "BCP SOLES",
"reference": "OP-458721",
"payment": 20.0
},
"summary": {
"total": 50.0,
"total_paid": 20.0,
"total_difference": 30.0
}
},
"message": "Pago registrado con éxito"
}
422 — Monto inválido
{
"success": false,
"message": {
"payment": [
"El campo payment debe ser mayor que 0."
]
}
}
409 — Sin caja abierta
{
"success": false,
"message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.