Registrar pago recibido (Yape / Plin)
POST /api/received-payments
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra en la bandeja un pago capturado de una notificación de Yape / Plin. Es idempotente por dedup_hash: si el mismo pago se envía de nuevo responde el registro existente con duplicated: true.
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. Además de data trae duplicated (boolean).
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
provider |
string | Sí | Proveedor: YAPE o PLIN. |
amount |
numeric | Sí | Monto recibido, mayor que 0. |
sender_name |
string | No | Nombre del remitente (máx. 255). |
raw_text |
string | Sí | Texto completo de la notificación. |
package_name |
string | Sí | Aplicación que generó la notificación (máx. 255). |
posted_at |
datetime | Sí | Fecha y hora del pago. ISO 8601; si viene en UTC (Z) se convierte a la hora local de la empresa. |
device_id |
string | Sí | Identificador del equipo que capturó el pago (máx. 255). |
dedup_hash |
string | Sí | Huella única del pago, para evitar duplicados (máx. 255). |
Reglas:
- El pago nuevo queda en estado
pendingy se notifica en tiempo real a las pantallas conectadas.
Errores:
422{success: false, message: {campo: [errores]}}si falla la validación de campos.
Cuerpo
Content-Type: application/json
{
"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-07T18:42:05Z",
"device_id": "caja-1-android",
"dedup_hash": "a3f1c9e2b7d4"
}
Respuestas
200 — Registrado
{
"success": true,
"message": "Pago registrado 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": "pending",
"matched_document_id": null,
"matched_document_payment_id": null,
"claimed_by_user_id": null,
"created_at": "2026-11-07 13:42:06"
},
"duplicated": false
}
200 — Duplicado
{
"success": true,
"message": "El pago ya habia sido registrado",
"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": "pending",
"matched_document_id": null,
"matched_document_payment_id": null,
"claimed_by_user_id": null,
"created_at": "2026-11-07 13:42:06"
},
"duplicated": true
}
422 — Validación
{
"success": false,
"message": {
"amount": [
"El campo amount debe ser mayor que 0."
]
}
}
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.