Webhooks | ProntoPaga Docs

¿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:

Crea un endpoint para recibirlo, es decir, crea una nueva ruta con la URL deseada.
Ajusta la llamada HTTP de tu endpoint a POST.
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.

Política de reintentos automáticos

Si el webhook no recibe una respuesta HTTP 200, ProntoPaga registrará el intento de envío y aplicará una política de reintentos automáticos. Se realizarán hasta 3 intentos en total: el envío inicial y 2 reintentos, sin tiempo de espera entre ellos. Se realizará un reintento cada vez que no se reciba una respuesta HTTP 200. Después del tercer intento, no se realizarán nuevos reintentos.

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.

Evento	Cuando se envía	Identificador para idempotencia
PayIn	Cuando los fondos se abonan en la cuenta interna de moneda local.	`transactionId`
Reembolso	Cuando el estado cambia a `on_hold`, `completed` o `failed`, y cuando el movimiento es revertido.	`refundId`
PayOut	Cuando el estado cambia a `on_hold`, `completed` o `failed`, y cuando el movimiento es revertido.	`payoutId`
Wire out	Cuando el estado cambia a `in_transit`, `completed` o `failed`.	`wireOutId`
Prefund USD	Cuando el estado cambia a `completed` o `failed`.	`prefundId`
Prefund local	Cuando los fondos se abonan en la cuenta interna de moneda local.	`transactionId`

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 abonos.

Estructura del webhook

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

Campo	Tipo	Descripción
`transactionId`	string	Identificador único del Pay In generado por ProntoPaga. Úselo para conciliación e idempotencia.
`amount`	number	Monto recibido.
`currency`	string	Código de la moneda, por ejemplo `PEN`.
`vaNumber`	string	Número de la cuenta virtual que recibió los fondos.
`comment`	string	Información adicional o referencia descriptiva del pago.
`payer`	object	Objeto que agrupa los datos del pagador.
`name`	string	Nombre o razón social del pagador.
`bank`	object	Objeto que agrupa los datos del banco de origen.
`id`	string	Identificador del banco.
`code`	string	Código local del banco.
`name`	string	Nombre del banco de origen.
`account`	object	Objeto que agrupa los datos de la cuenta bancaria de origen.
`number`	string	Número de la cuenta bancaria de origen.
`type`	string	Tipo de cuenta bancaria, por ejemplo `checking`.
`document`	object	Objeto que agrupa los datos de identificación del pagador.
`type`	string	Tipo de documento, por ejemplo `ruc`.
`id`	string	Número del documento.

Ejemplo de un webhook para PayIns

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

{
  "transactionId": "c8e4d1f0-9a2b-4c3d-8e5f-6a7b8c9d0e1f",
  "amount": 25000,
  "currency": "PEN",
  "vaNumber": "00219300012345678901",
  "comment": "Payin received from Alfin Banco",
  "payer": {
    "name": "ACME Corporation S.A.C.",
    "bank": {
      "id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "code": "003",
      "name": "Banco Alfin",
      "account": { 
        "number": "19100012345678",
        "type": "checking"
      }
    },
    "document": {
      "type": "ruc",
      "id": "20512345678"
    }
  }
}

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 interna en moneda local.

Estructura del webhook

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

Campo	Tipo	Descripción
`payoutId`	string	Identificador único del Payout generado por ProntoPaga.
`amount`	number	Monto del Payout.
`currency`	string	Código ISO 4217 de la moneda, por ejemplo `CLP`.
`status`	string	Estado actual del Payout. Ejemplo: `completed`.
`statusMessage`	string	Mensaje descriptivo asociado al estado actual.
`reason`	string	Motivo del fallo. Solo se envía cuando `status` es `failed`.
`comment`	string	Información adicional sobre el Payout.
`referenceId`	string	Referencia proporcionada por el comercio para rastrear la operación.
`createdAt`	string (date-time)	Fecha y hora de creación en formato ISO 8601.
`updatedAt`	string (date-time)	Fecha y hora de la última actualización en formato ISO 8601.
`isReversed`	boolean	Indica que el Payout fue revertido. Solo se incluye si existe un reverso.
`reversedAt`	string (date-time)	Fecha y hora del reverso en formato ISO 8601.
`reversalTransactionId`	string	Identificador de la transacción de reverso.

Ejemplo de un webhook para PayOuts

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

{
  "payoutId": "d4c3b2a1-6f5e-4807-b1a9-3d2c1e4f5a60",
  "amount": 1250000,
  "currency": "CLP",
  "status": "completed",
  "statusMessage": "PayOut request successfully executed",
  "reason": "",
  "comment": "Payout settled to beneficiary account",
  "referenceId": "MERCH-PAYOUT-2026-000123",
  "createdAt": "2026-08-18T13:45:02.117Z",
  "updatedAt": "2026-08-18T14:02:31.480Z",
  "isReversed": true,
  "reversedAt": "2026-08-18T11:05:37-05:00",
  "reversalTransactionId": "g6d4c3b2-7g6f-5918-a2a0-4e3d2f5g6b71"
}

🚧
Ten en cuenta que

El campo reason solo aplica cuando el estado del PayOut sea failed.

Los campos isReversed, reversedAt y reversalTransactionId solo aplican si existe un reverso.

Webhook reembolsos

El servicio de notificación vía webhook de ProntoPaga permite a los comercios recibir actualizaciones automáticas cada vez que se realicen reembolsos desde una cuenta interna en moneda local.

Estructura del webhook

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

Campo	Tipo	Descripción
`vaNumber`	string	Número de la cuenta virtual desde la cual se originó el reembolso.
`amount`	number	Monto reembolsado.
`currency`	string	Código ISO 4217 de la moneda, por ejemplo `PEN`.
`originalTransactionId`	string	Identificador del Pay In original al que corresponde el reembolso.
`refundId`	string	Identificador único del reembolso generado por ProntoPaga.
`status`	string	Estado actual del reembolso. Ejemplo: `completed`.
`statusMessage`	string	Mensaje descriptivo asociado al estado actual.
`reason`	string	Motivo del fallo. Solo se envía cuando `status` es `failed`.
`comment`	string	Información adicional sobre el reembolso.
`type`	string enum	Tipo de reembolso: `partial` o `total`.
`referenceId`	string	Referencia proporcionada por el comercio para rastrear el reembolso.
`createdAt`	string (date-time)	Fecha y hora de creación del reembolso en formato ISO 8601.
`updatedAt`	string (date-time)	Fecha y hora de la última actualización en formato ISO 8601.
`isReversed`	boolean	Indica que el reembolso fue revertido. Solo se incluye si existe un reverso.
`reversedAt`	string (date-time)	Fecha y hora del reverso en formato ISO 8601.
`reversalTransactionId`	string	Identificador de la transacción de reverso.

Ejemplo del webhook para reembolsos

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

{
  "vaNumber": "1053800200004871",
  "amount": 500.00,
  "currency": "PEN",
  "originalTransactionId": "358d7639-9a16-47a9-a379-20953df0ca3b",
  "refundId": "5b49bd3c-62cb-4e02-8410-9eb3ee684658",
  "status": "completed",
  "statusMessage": "Refund request successfully executed",
  "reason": "",
  "comment": "Refund settled to beneficiary account",
  "type": "partial",
  "referenceId": "MERCH-REFUND-2026-000123",
  "createdAt": "2026-08-18T13:45:02.117Z",
  "updatedAt": "2026-08-18T14:02:31.480Z",
  "isReversed": true,
  "reversedAt": "2026-08-18T11:05:37-05:00",
  "reversalTransactionId": "g6d4c3b2-7g6f-5918-a2a0-4e3d2f5g6b71"
}

🚧
Ten en cuenta que

El campo reason solo aplica cuando el estado del reembolso sea failed.

Los campos isReversed, reversedAt y reversalTransactionId solo aplican si existe un reverso.

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.

Estructura del webhook

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

Campo	Tipo	Descripción
`wireOutId`	string	Identificador único del Wire Out generado por ProntoPaga.
`referenceId`	string	Referencia de la operación utilizada por el comercio para conciliación.
`status`	string	Estado actual del Wire Out. Ejemplo: `completed`.
`statusMessage`	string	Mensaje descriptivo asociado al estado actual.
`currency`	string	Código ISO 4217 de la moneda, por ejemplo `USD`.
`amount`	number	Monto de la transferencia.
`updatedAt`	string (date-time)	Fecha y hora de la última actualización en formato ISO 8601.
`createdAt`	string (date-time)	Fecha y hora de creación en formato ISO 8601.
`voucher`	string	URL HTTPS del comprobante de la operación.

Ejemplo de webhook para wire outs

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

{
  "wireOutId": "0a5b4888-e81c-488b-b0ad-8c83074904f2",
  "referenceId": "WO26081800471",
  "status": "completed",
  "statusMessage": "Wire out request successfully executed",
  "currency": "USD",
  "amount": 250.35,
  "updatedAt": "2026-08-20T16:42:10-05:00",
  "createdAt": "2026-08-18T11:05:37-05:00",
  "voucher": "https://vouchers.prontopaga.com/wire-out/86487a20-a593-43fd-85b4-97400bdd2631.pdf"
}

Webhook Prefund USD

Notifica la recepción o actualización de un fondeo en USD a la cuenta interna en USD e identifica la cuenta receptora y el banco del pagador.

Estructura del webhook

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

Campo	Tipo	Descripción
`prefundId`	string	Identificador único del Prefund generado por ProntoPaga.
`accountNumber`	string	Identificador o número de la cuenta receptora del fondeo.
`amount`	number	Monto recibido.
`payer`	object	Objeto que agrupa los datos del pagador.
`name`	string	Nombre o razón social del pagador.
`bank`	object	Objeto que agrupa los datos del banco de origen.
`name`	string	Nombre del banco de origen.
`swift`	string	Código BIC/SWIFT del banco de origen.
`comment`	string	Se utiliza cuando se haya reversado un wire out.
`status`	string	Estado actual del Prefund. Ejemplo: `completed`.
`statusMessage`	string	Mensaje descriptivo asociado al estado actual.
`reason`	string	Motivo del fallo. Solo se envía cuando `status` es `failed`.

Ejemplo de webhook para prefund en USD

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

{
  "prefundId": "a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6071",
  "accountNumber": "9c1f8e7d-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
  "amount": 15000.5,
  "payer": {
    "name": "ACME Corporation S.A.C.",
    "bank": {
      "name": "Banco Alfin",
      "swift": "ALFNPEPL"
     }
  },
  "comment": "This is a reverse from the wireOut: 0a5b4888-e81c-488b-b0ad-8c83074904f2",
  "status": "completed",
  "statusMessage" :"Prefund request successfully executed",
  "reason": "Invalid payment receipt"
}

🚧
Ten en cuenta que

El campo reason solo aplica cuando el estado del prefund en USD sea failed.

Webhook Prefund local

Notifica un fondeo en moneda local e incluye los datos bancarios y documentales disponibles del pagador.

País	Código del país (ISO 3166-1 alpha-2)	Código de moneda (ISO 4217)
Chile	CL	CLP
Perú	PE	PEN

Estructura del webhook

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

Campo	Tipo	Descripción
`amount`	number	Monto recibido.
`transactionId`	string	Identificador único de la transacción de Prefund local.
`payer`	object	Objeto que agrupa los datos del pagador.
`name`	string	Nombre o razón social del pagador.
`bank`	object	Objeto que agrupa los datos del banco de origen.
`id`	string	Identificador del banco.
`code`	string	Código local del banco.
`name`	string	Nombre del banco de origen.
`account`	object	Objeto que agrupa los datos de la cuenta bancaria de origen.
`number`	string	Número de la cuenta bancaria de origen.
`type`	string	Tipo de cuenta bancaria, por ejemplo `checking`.
`document`	object	Objeto que agrupa los datos de identificación del pagador.
`type`	string	Tipo de documento, por ejemplo `ruc`.
`id`	string	Número del documento.
`accountNumber`	string	Identificador o número de la cuenta receptora del fondeo.

Ejemplo de webhook para prefund local

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

{
  "amount": 15000.5,
  "transactionId": "c8e4d1f0-9a2b-4c3d-8e5f-6a7b8c9d0e1f",
  "payer": {
    "name": "ACME Corporation S.A.C.",
    "bank": {
      "id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "code": "003",
      "name": "Banco Alfin",
      "account": {
        "number": "19100012345678",
        "type": "checking"
      }
    },
    "document": {
      "type": "ruc",
      "id": "20512345678"
    }
  },
  "accountNumber": "9c1f8e7d-6a5b-4c3d-8e2f-1a0b9c8d7e6f"
}