Reclamar pago recibido y asignarlo a un comprobante
POST /api/received-payments/{received_payment_id}/claim
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Asigna un pago pendiente a un comprobante: registra el pago del comprobante con el monto y la fecha del pago recibido y el método/destino que envías, y el pago pasa a matched. Es atómico: si dos usuarios lo reclaman a la vez, solo uno lo consigue.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).
Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success.
Parámetros de la URL:
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
id |
integer | Sí | Id del pago recibido. |
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
document_id |
integer | Sí | Id del comprobante a pagar (debe existir). |
payment_method_type_id |
string | Sí | Método de pago existente (p. ej. el de Yape o Plin de la empresa). |
payment_destination_id |
string/integer | Sí | cash o id de cuenta bancaria / billetera. |
Reglas de caja: cuando una regla de caja impide la operación responde 422 con {success: false, message, cash_rule: true}; el message explica la causa y puede mostrarse al usuario tal cual (caja cerrada, sin caja abierta para un pago en efectivo, pago duplicado en menos de 20 segundos, etc.).
Errores:
409si el pago ya fue reclamado o descartado.422{success: false, message: {campo: [errores]}}si falla la validación de campos.422concash_rule: truesi una regla de caja lo impide.500si el id no existe (el mensaje técnico no es apto para mostrar al usuario: valida el id antes).
Parámetros
| Parámetro | Dónde | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
received_payment_id |
ruta | sí | 1 |
Cuerpo
Content-Type: application/json
{
"document_id": "1",
"payment_method_type_id": "12",
"payment_destination_id": 3
}
Respuestas
200 — Reclamado
{
"success": true,
"message": "Pago reclamado y asignado al comprobante con exito",
"data": {
"id": 12,
"provider": "YAPE",
"amount": 25.5,
"sender_name": "MARIA LOPEZ",
"raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
"package_name": "com.bcp.innovacxion.yapeapp",
"posted_at": "2026-11-07 13:42:05",
"device_id": "caja-1-android",
"dedup_hash": "a3f1c9e2b7d4...",
"status": "matched",
"matched_document_id": 1520,
"matched_document_payment_id": 58,
"claimed_by_user_id": 5,
"created_at": "2026-11-07 13:42:06"
}
}
409 — Ya procesado
{
"success": false,
"message": "El pago ya fue procesado por otro dispositivo."
}
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.