Webhook de notificación

Usa el webhook de notificaciones para recibir updates sobre el estado de pagos realizadon con nuestro widget.

Para poder recibir estas notificaciones, deberas seguir los siguientes pasos:

Exponer un endpoint desde tus servidores
Configurar tu webhook en el widget que desees usar
Recibir y procesar las notificaciones

Requerimientos para tu endpoint

Las notificaciones son enviadas como llamadas HTTP a un endpoint en tus servidores. Requerimos que uses https para este endpoint.

Para asegurarnos que estás recibiendo las notificaciones correctamente, tu endpoint deberá responder con un código HTTP 200.

Es posible que tengas que configurar tu firewall o WAF para que acepte requests de nuestras IPs. Estas serán: 107.23.220.24, 23.22.34.57 y 3.83.0.169

🚧
Reintento de notificaciones
Si respondes con un codigo fuera del rango 2XX o demoras mas de 5 segundos en responder, volveremos a intentar luego de un tiempo. Deberas encargarte de deduplicar eventos usando el identificador del mismo.

Configuracion del webhook

Para que podamos enviarte notificaciones, deberas configurar los siguientes campos en tu widget:

URL del endpoint al que llamaremos.
Token de verificacion, un string generado por ti que usaras para verificar las llamadas que hagamos a tu endpoint.

Procesando eventos

Al recibir una notificacion, deberas seguir los siguientes pasos:

Comparar el campo verify_tokencon el que configuraste en tu widget para asegurarte que la llamada es autentica.
Almacenar la notificacion en tu base de datos
Devolver una respuesta a la llamada con un codigo 2XX
Procesar la notificacion con tu logica de negocio.

Estructura de notificaciones

Tu endpoint recibira una llamada POSTconteniendo un JSON con la siguiente estructura:

{
  "verify_token": "TOKEN",
  "events": [
    {
      "event_type": "payment.success",
      "event_id": "e9af15dd-b9e7-4481-8d19-a782fc6b68bf",
      "timestamp": "2022-10-19T13:10:37Z",
      "payload": {}
    }
  ]
}

Campo	Descripcion
`verify_token`	El token de verificacion definido en tu widget
`events`	Lista de eventos generados
`events.event_type`	El tipo de evento
`events.event_id`	Identificador del evento, usado para deduplicacion
`events.timestamp`	Timestamp de creacion del evento
`events.payload`	Objeto JSON especifico para cada evento. Ver tabla a continuación.

Objeto Payload

Campo	Descripción
`amount`	Cantidad a transferir
`concept`	Concepto o descripcion de la transferencia
`currency`	Moneda de la cuenta en formato ISO 4217, por ejemplo UYU o USD
`origin_account`	Número de cuenta de donde se transfiere
`destination_institution`	ID de la institucion a donde se transfiere, el id se obtiene en el endpoint de listar instituciones para transferencias
`destination_account_type`	Tipo de la cuenta destino (`CA`: Caja Ahorros, `CC`: Cuenta Corriente)
`document_type`	Tipo de Documento asociada a la cuenta destino
`destination_account`	Número de cuenta a donde se transfiere
`destination_bank_code`	Código de banco destino.
`request_id`	ID de la transcaccion generado por Prometeo
`operation_id`	ID de la operación informado por el banco
`intent_id` (new)	ID del intento de pago

`payment.success`

A continuación listamos un ejemplo de pago exitoso:

{
  "verify_token": "310XXXX4",
  "events": [
    {
      "event_type": "payment.success",
      "event_id": "209f681b-XXXX-4238-XXXX-2204XXXX27cf",
      "timestamp": "2023-01-31T21:04:37.781798",
      "payload": {
        "amount": "1",
        "concept": "payment1987",
        "currency": "USD",
        "origin_account": "19322XXXXXXXX45",
        "destination_account": "19395XXXXXXXX150",
        "destination_institution": "0",
        "branch": "0",
        "destination_owner_name": "CONSULTORA XXXXXXXX SAC",
        "destination_account_type": null,
        "document_type": null,
        "document_number": null,
        "destination_bank_code": "bcp_pe",
        "mobile_os": null,
        "request_id": "5ba13cd5a9XXXXXXXX521269ac13bb5a",
        "intent_id": "aaa13cd5a9XXXXXXXX521269ac13bb5a"
      }
    }
  ]
}

`payment.error`

A continuación listamos un ejemplo de pago con error:

{
  "verify_token": "31XX234",
  "events": [
    {
      "event_type": "payment.error",
      "event_id": "976306fa-XXXX-4d86-XXXX-af2XXX89fbd8",
      "timestamp": "2023-01-31T21:03:15.912182",
      "payload": {
        "amount": "1",
        "concept": "payment1234",
        "currency": "USD",
        "origin_account": "1932XXXXXX0145",
        "destination_account": "19395XXXXXX150",
        "destination_institution": "0",
        "branch": "0",
        "destination_owner_name": "CONSULTORA XXXXXXXXX SAC",
        "destination_account_type": null,
        "document_type": null,
        "document_number": null,
        "destination_bank_code": "bcp_pe",
        "mobile_os": null,
        "request_id": "5ba13cd5XXXXXXXXX269ac13bb5a",
        "intent_id": "aaa13cd5a9XXXXXXXX521269ac13bb11"
      }
    }
  ]
}

`payment.rejected`

A continuación listamos un ejemplo de pago rechazado:


{
  "verify_token": "31XXXXXXXX33",
  "events": [
    {
      "event_type": "payment.rejected",
      "event_id": "dec4cc14-XXX-4ab0-XXXX-XXXXXXXX",
      "timestamp": "2023-01-31T20:05:36.657998",
      "payload": {
        "amount": "3",
        "concept": "payment48769324",
        "currency": "PEN",
        "origin_account": "918XXXXXXXX285",
        "destination_account": "0111790XXXXXXXX3094",
        "destination_institution": "1",
        "branch": "0",
        "destination_owner_name": "CONSULTORA XXXXXXXX SAC",
        "destination_account_type": null,
        "document_type": null,
        "document_number": null,
        "destination_bank_code": "bbva_pe",
        "mobile_os": null,
        "request_id": "0b292df497XXXXXXXXca653e320e",
        "intent_id": "aaa13cd5a9XXXXXXXX521269ac13bb11"
      }
    }
  ]
}

`payment.cancelled`

A continuación listamos un ejemplo de pago rechazado:

{
  "verify_token": "31XXX33",
  "events": [
    {
      "event_type": "payment.cancelled",
      "event_id": "f7a92b6f-XXX-449b-9257-XXXXXXXX",
      "timestamp": "2023-01-31T20:07:01.233425",
      "payload": {
        "amount": 1,
        "concept": "payment46782364",
        "currency": "PEN",
        "origin_account": "1933XXXXXXXX5033",
        "destination_account": "011179XXXXXXXX3094",
        "destination_institution": 19,
        "branch": null,
        "destination_owner_name": "CONSULTORA XXXXXXXX SAC",
        "destination_account_type": null,
        "document_type": null,
        "document_number": null,
        "destination_bank_code": "bbva_pe",
        "request_id": "8b211a6bXXXXXXXX9b6d278173db",
        "intent_id": "aaa13cd5a9XXXXXXXX521269ac13bb11"
      }
    }
  ]
}