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:
- 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_token
con 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 POST
conteniendo 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
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
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
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
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"
}
}
]
}
Updated about 1 month ago