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 verificación, un string generado por ti que usaras para verificar las llamadas que hagamos a tu endpoint.

Procesando eventos

Al recibir una notificación, deberás seguir los siguientes pasos:

Comparar el campo verify_tokencon el que configuraste en tu widget para asegurarte que la llamada es auténtica.
Almacenar la notificación en tu base de datos
Devolver una respuesta a la llamada con un código 2XX
Procesar la notificación con tu lógica de negocio.

Estructura de notificaciones

Tu endpoint recibirá 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 de duplicacion
`events.timestamp`	Timestamp de creación 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 descripción 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_account`	Número de cuenta a donde se transfiere
`destination_institution`	ID de la institución 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 asociado 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 transacción generado por Prometeo
`intent_id`	ID del intento de pago
`operation_id`	ID de la operación informado por el banco
`external_id`	ID alfanumérico proporcionado para rastrear y gestionar tus pagos internamente

Objeto informed by merchant

Campo	Descripción
`document_number`	Número de documento que identifica a un usuario.
`username`	Nombre de usuario que identifica al sujeto en la plataforma del comerciante.
`reference`	Referencia adicional para el comerciante.

`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",
        "operation_id":"123123",
        "external_id": "bf5d88cc-f60c-4612-8739-15b3244fcd04"
      },
      "informed_by_merchant":{
                "document_number": "12345678",
                "username": "Name Surname",
                "reference": "user-reference"
      }
    }
  ]
}

`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",
        "operation_id": null,
        "external_id": "bf5d88cc-f60c-4612-8739-15b3244fcd04"
      },
      "informed_by_merchant":{
                "document_number": "12345678",
                "username": "Name Surname",
                "reference": "user-reference"
      }
    }
  ]
}

`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",
        "operation_id": null,
        "external_id": "bf5d88cc-f60c-4612-8739-15b3244fcd04"
      },
      "informed_by_merchant":{
                "document_number": "12345678",
                "username": "Name Surname",
                "reference": "user-reference"
      }
    }
  ]
}

`payment.cancelled`

A continuación listamos un ejemplo de pago cancelado:

{
  "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",
        "external_id": "bf5d88cc-f60c-4612-8739-15b3244fcd04"
      },
      "informed_by_merchant":{
                "document_number": "12345678",
                "username": "Name Surname",
                "reference": "user-reference"
      }
    }
  ]
}

Requerimientos para tu endpoint

🚧Reintento de notificaciones

Configuracion del webhook

Procesando eventos

Estructura de notificaciones

Objeto Payload

Objeto informed by merchant

payment.success

payment.error

payment.rejected

payment.cancelled

🚧
Reintento de notificaciones

`payment.success`

`payment.error`

`payment.rejected`

`payment.cancelled`