Saltar al contenido
Facturador

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 pending y 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.