Webhook de notificación

Recibe notificaciones de eventos en Prometeo

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:

  1. Exponer un endpoint desde tus servidores
  2. Configurar tu webhook en el widget que desees usar
  3. 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:

  1. Comparar el campo verify_tokencon el que configuraste en tu widget para asegurarte que la llamada es autentica.
  2. Almacenar la notificacion en tu base de datos
  3. Devolver una respuesta a la llamada con un codigo 2XX
  4. 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": {}
    }
  ]
}
CampoDescripcion
verify_tokenEl token de verificacion definido en tu widget
eventsLista de eventos generados
events.event_typeEl tipo de evento
events.event_idIdentificador del evento, usado para deduplicacion
events.timestampTimestamp de creacion del evento
events.payloadObjeto JSON especifico para cada evento. Ver tabla a continuación.

Objeto Payload

CampoDescripción
amountCantidad a transferir
conceptConcepto o descripcion de la transferencia
currencyMoneda de la cuenta en formato ISO 4217, por ejemplo UYU o USD
origin_accountNúmero de cuenta de donde se transfiere
destination_institutionID de la institucion a donde se transfiere, el id se obtiene en el endpoint de listar instituciones para transferencias
destination_account_typeTipo de la cuenta destino (CA: Caja Ahorros, CC: Cuenta Corriente)
document_typeTipo de Documento asociada a la cuenta destino
destination_accountNúmero de cuenta a donde se transfiere
destination_bank_codeCódigo de banco destino.
request_idID de la transcaccion generado por Prometeo
operation_idID 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"
      }
    }
  ]
}