Webhooks

¿Qué son los webhooks?

Los webhooks nos permiten notificarte sobre eventos ocurridos con las cuentas virtuales. Son útiles para actualizaciones, como cuando un pago es confirmado, una solicitud de reembolso ha sido completada con éxito o un wire out está en proceso.

Configura un webhook

Para iniciar la configuración de tu webhook, sigue estos pasos:

1. Crea un endpoint para recibirlo, es decir, crea una nueva ruta con la URL deseada.
2. Ajusta la llamada HTTP de tu endpoint a POST.
3. Agrega el body en formato JSON.

Método de autenticación

ProntoPaga firma todas las solicitudes de webhook con una apiKey para verificar su autenticidad.

Webhook Payloads

A continuación se presentan los campos más importantes que pueden aparecer en los distintos webhooks. Para cada campo, se explica qué representa y cómo se utiliza según el tipo de evento, ya sea un pago recibido, un reembolso o un wire out.

Webhook PayIns

El servicio de notificación vía webhook de ProntoPaga está diseñado para notificar automáticamente a los comercios cada vez que una cuenta virtual reciba un PayIn. Esto te permite mantener actualizados tus sistemas de ventas y automatizar procesos de conciliación.

A continuación, puedes conocer la estructura del webhook:

Proceso de notificaciones PayIns

A continuación, se detalla el proceso de notificación mediante webhooks para payins de cuentas virtuales en ProntoPaga:

1. Recepción de pago. ProntoPaga recibe el pago en la cuenta virtual del comercio.
2. Validación. ProntoPaga valida los detalles del pago, incluyendo el monto, la cuenta activa y el comercio al que pertenece la cuenta virtual.
3. Notificación al comercio. Una vez validado el pago, ProntoPaga envía una notificación a la URL configurada por el comercio, con los detalles del pago recibido.

Este es un ejemplo de webhook que podrías recibir.

{
  "payinId": "TX987654321",
  "vaNumber": "CCIV-00012345",
  "amount": {
    "currency": "PEN",
    "value": 1500
  },
  "payer": {
    "name": "Jane Doe",
    "document": {
      "type": "DNI",
      "id": "87654321"
    },
    "bank": {
      "name": "BCP",
      "code": "002"
    }
  },
  "account": {
    "number": "000987654321",
    "type": "ahorros"
  },
  "comment": "reference"
}

Webhook PayOuts

El servicio de notificación vía webhook de ProntoPaga permite a los comercios recibir actualizaciones automáticas cada vez que se dispersen fondos desde una cuenta virtual como parte de un reembolso (refund) asociado a un PayIn.

A continuación, puedes conocer la estructura del webhook:

Proceso de notificaciones reembolsos

A continuación, se detalla el proceso de notificación mediante webhooks para reembolsos hacia cuentas virtuales:

1. Cambio de estado de reembolso. Cada vez que el estado de un reembolso asociado a un pago realizado por cuenta virtual cambia (desde received hasta completed), ProntoPaga enviará una notificación al endpoint URL configurado por el comercio.
2. Validación y envío. El sistema de ProntoPaga valida la información del reembolso y envía una notificación con los detalles del reembolso y su estado actualizado.

Este es un ejemplo de webhook que podrías recibir.

{
  "vaNumber": "1234567890",
  "amount": {
    "currency": "PEN",
    "value": 1000
  },
  "payinId": "abc123xyz",
  "refundId": "refund789",
  "status": "received",
  "comment": "Reembolso parcial solicitado por el cliente.",
  "type": "partial",
  "referenceId": "ref12345"
}

Webhook Wire outs

El servicio de notificación de estado de Wire Out tiene como objetivo informar a los comercios sobre cambios relevantes en el estado de una operación de wire out realizada desde ProntoPaga. Este mecanismo de webhooks se activa cada vez que el estado de un wire out cambia, específicamente cuando el estado es Processing, Success o Failed.

A continuación, puedes conocer la estructura del webhook:

Proceso de notificaciones wire outs

A continuación, se detalla el proceso de notificación mediante webhooks para wire outs en ProntoPaga:

1. Cambio de estado en ProntoPaga:
   Cuando el estado de un wire out cambia (por ejemplo, de Processing a Success o Failed), ProntoPaga envía una notificación al endpoint del comercio configurado para recibir los webhooks.

2. Generación del webhook:
   El webhook incluirá los detalles del wire out, tales como:

   • wireOutId
   • referenceId
   • processingStatus
   • currency
   • amount
   • updatedAt
   • Otros campos relevantes El envío se realiza solo después de que el estado ha sido registrado en el sistema de ProntoPaga.

3. Reintentos automáticos:
   Si el webhook no es recibido correctamente (es decir, la respuesta no es HTTP 200), ProntoPaga registrará el intento de envío y aplicará una política de reintentos automáticos.

4. Actualización del comercio:
   Una vez recibido el webhook, el comercio podrá actualizar su plataforma, asegurando que los estados transaccionales estén sincronizados correctamente.

Este es un ejemplo de webhook que podrías recibir.

{
  "wireOutId": "wo_20260414_001",
  "referenceId": "XT12340260414WO001",
  "processingStatus": "Success",
  "statusMessage": "Wire out ejecutado correctamente vía SWIFT",
  "currency": "USD",
  "amount": 1500,
  "updatedAt": "2026-04-14T19:10:00-05:00",
  "completedAt": "2026-04-14T19:10:00-05:00"
}