Webhooks de Pagos (Brasil)

Un webhook es una devolución de llamada web que Belvo utiliza para enviar notificaciones sobre un enlace específico.

Este artículo trata sobre webhooks para nuestra solución de Iniciación de Pagos. Para obtener información sobre nuestros webhooks de Agregación y Enriquecimiento, consulta este artículo

Configurar webhooks

Para configurar un nuevo webhook:

En tu panel de control de Belvo, ve a la sección de webhooks de pagos.
En la pestaña de Payments Webhooks, haz clic en +New webhook.
Completa el formulario de New webhook con la información requerida.
- URL: la URL para recibir las notificaciones del webhook.
- Authorization: un token bearer opcional para usar si tu URL está protegida.
Haz clic en Create webhook.

Tipos de webhook

Todos los eventos de webhook vienen con una carga útil principal (como se describe en el ejemplo de código a continuación).

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "The payment consent was not accepted in time.",
    "end_to_end_id": "E432158152024081610416f2b595b056",
  }
}

Parámetro	Requerido	Tipo	Descripción	Ejemplo
`webhook_id`	si	string	El ID del webhook de Belvo.	`aadf41a1fc8e4f79a49f7f04027ac999`
`webhook_type`	si	string	El recurso al que se refiere este webhook.	`CHARGES`
`webhook_code`	si	string	El evento que activó el webhook.	`STATUS_UPDATE`
`object_id`	si	string	El ID del objeto al que se refiere este webhook.	`d2e40773-19f6-48d1-93c3-3590ec0c74df`
`external_id`	si	string	El identificador único que proporcionaste al crear el objeto. Para cargos y transacciones, este campo siempre devolverá `null`.	`c3c51aaf-aaa3-400c-926d-87ab62e195fd`
`data`	si	object	Un objeto que contiene datos específicos sobre el evento. Los campos devueltos en este objeto dependen del `webhook_type` y `webhook_code`.	Ver filas siguientes.
`data.status`	no	string	El estado del cargo o intención de pago.	`FAILED`
`data.failure_code`	no	string	En caso de que el cargo o la intención de pago falle, un código único para el error.	`consent_expired`
`data.failure_message`	no	string	En caso de que el cargo o la intención de pago falle, una descripción del error en lenguaje humano.	`The payment consent was not accepted in time.`
`data.end_to_end_id`	no	string	El ID del pago en el sistema de pagos de Brasil.	`E432158152024081610416f2b595b056`
`data.metadata`	no	object	Si proporcionaste alguna información en el objeto `metadata` al crear tu pago, se incluye en el cuerpo del webhook.	`{ "internal_reference_id": "GGq12345w2" }`

Para obtener información sobre los datos específicos de un webhook dado, haz clic en el tipo de webhook en la tabla a continuación.

Tipo	Evento	Enviado siempre que...
CHARGES	`STATUS_UPDATE`	Hay una actualización en el estado de una intención de pago
PAYMENT_INTENTS	`STATUS_UPDATE`	Hay una actualización en el estado de una intención de pago.
TRANSACTIONS	`OBJECT_CREATED`	Se ha creado una nueva transacción.

Direcciones IP de salida del webhook

Puedes recibir eventos de webhook desde las siguientes direcciones IP:

3.130.254.46
18.220.61.186
18.223.45.212

Recomendamos encarecidamente que pongas en la lista blanca estas direcciones IP para que puedas recibir eventos de webhook.

Mejores prácticas para la respuesta del webhook del lado del cliente

Recomendamos encarecidamente que una vez que recibas un webhook, respondas a Belvo con un código de estado 2XX dentro de cinco segundos para confirmar que has recibido el webhook. De lo contrario, nuestra API volverá a intentar la solicitud.

Política de reintento de webhook

Si nuestro sistema no recibe un código de estado 2XX, intenta automáticamente enviar la solicitud nuevamente. Este proceso de reintento ocurrirá hasta tres veces, con cada intento separado por 60 segundos. Por ejemplo, si el primer intento falla, nuestro sistema espera 60 segundos antes de intentar nuevamente y continuará con este patrón hasta que reciba una respuesta exitosa o alcance el máximo de tres reintentos.

slug: "ofpi-webhooks"

Cargos

STATUS_UPDATE

Recibirás un evento de webhook cada vez que el estado de un cargo se actualice a:

Evento	Enviado cuando
`SCHEDULED`	El cargo está 'pausado' hasta la fecha de pago programada.
`SUCCEEDED`	El cargo ha sido confirmado y procesado por la red de finanzas abiertas.
`FAILED`	El usuario no ha proporcionado consentimiento para el pago, o ha habido un error general en la red de finanzas abiertas.
`CANCELED`	El cargo programado fue cancelado.

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CHARGES",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": null,
  "data": {
    "status": "SUCCEEDED", // El estado del cargo.
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": null,
    "failure_message": null,
    "end_to_end_id": "E432158152024081610416f2b595b056",
  },
}

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CHARGES",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": null,
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "El consentimiento de pago no fue aceptado a tiempo.",
    "end_to_end_id": "E432158152024081610416f2b595b056"
  }
}

Códigos de falla y mensajes

A continuación se muestra una lista de failure_codes y failure_messages que puedes recibir en un webhook de Cargos cuando un cargo falla:

Código	Mensaje	Cuándo puede ocurrir
`AMOUNT_OVER_LIMIT`	El monto del pago o el número de pagos excede los límites establecidos por la institución.	Actualización de Estado
`AUTHORIZATION_EXPIRED`	El tiempo de autorización ha expirado.	Actualización de Estado
`CONSENT_PENDING_AUTHORIZATION`	Consentimiento pendiente de autorización de múltiples niveles (estado 'PARTIALLY_ACCEPTED')."	Actualización de Estado
`HOLDER_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del titular de la cuenta.	Actualización de Estado
`ICP_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del ICP (Infraestrutura de Chaves Públicas).")	Actualización de Estado
`INSUFFICIENT_FUNDS`	La cuenta tiene fondos insuficientes para realizar el pago.	Actualización de Estado
`INVALID_CHARGE`	El cargo es inválido o incorrecto.	Actualización de Estado
`INVALID_PAYMENT_DETAIL`	Los detalles de pago proporcionados son inválidos.	Actualización de Estado
`NOT_INFORMED`	No se proporcionó una razón de error por parte de la institución.	Al Crear
`PAYMENT_CONSENT_MISMATCH`	Los detalles de pago no coinciden con el consentimiento proporcionado.	Al Crear
`PAYMENT_REFUSED_BY_HOLDER`	El pago fue rechazado por el titular de la cuenta.	Al Crear, Actualización de Estado
`PAYMENT_REFUSED_BY_SPI`	El pago fue rechazado por el SPI (Sistema de Pagamentos Instantâneos).	Actualización de Estado
`PAYMENT_SCHEDULING_FAILURE`	Hubo una falla al programar el pago.	Actualización de Estado
`RECEIVING_PSP_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del PSP receptor (Proveedor de Servicios de Pago).	Actualización de Estado
`SAME_ORIGIN_DESTINATION_ACCOUNTS`	Las cuentas de origen y destino son las mismas.	Actualización de Estado
`SPI_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del SPI.	Actualización de Estado
`SPI_REJECTED_PAYMENT`	Pago rechazado en el Sistema de Pagos Instantáneos (SPI).	Actualización de Estado
`USER_REJECTED`	El usuario rechazó la autorización del consentimiento.	Actualización de Estado

Clientes

OBJECT_CREATED

Cada vez que se crea un nuevo cliente mediante la aplicación de Belvo (es decir, cuando el cliente se crea de manera asincrónica y no como resultado de una llamada directa POST), recibirás el siguiente webhook:

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CUSTOMERS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": null
}

Una vez que recibas la notificación, puedes obtener detalles sobre el cliente haciendo la siguiente solicitud:

curl --request GET 'https://api.belvo.com/payments/br/customers/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Donde:

id es el object_id del cliente (que recibes en el evento del webhook).

Inscripciones

STATUS_UPDATE

Recibirás un evento de webhook cada vez que el estado de una inscripción se actualice a:

Evento	Enviado cuando
`PENDING`	La inscripción está esperando que se envíen los detalles biométricos.
`SUCCEEDED`	La inscripción fue aceptada por la institución.
`FAILED`	La inscripción fue rechazada por la institución.

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "06a51b80-708d-49c9-8620-7b0fd2fbc548",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "PENDING",
    "metadata": null,
    "details": { "status": "AWAITING_ENROLLMENT" }
  }
}

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "e64de9d0-0045-49ad-b1ee-779a9c269ab3",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "SUCCEEDED",
    "metadata": null,
    "details": { "status": "AUTHORIZED" }
  }
}

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "e64de9d0-0045-49ad-b1ee-779a9c269ab3",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": null,
    "details": { "status": "REJECTED" }
  }
}

Intenciones de pago

STATUS_UPDATE

Recibirás un evento de webhook cada vez que el estado de una intención de pago se actualice a:

Evento	Enviado cuando
`REQUIRES_PAYMENT_METHOD`	Se requieren detalles adicionales para completar el flujo de la intención de pago.
`REQUIRES_ACTION`	Has enviado `confirm=true` en el flujo de la intención de pago y Belvo ahora inicia el flujo de pago en la red de finanzas abiertas.
`PROCESSING`	El pago está siendo procesado en la red de finanzas abiertas.
`SCHEDULED`	El pago está 'pausado' hasta la fecha de pago programada.
`CANCELED`	La intención de pago programada fue cancelada.
`SUCCEEDED`	El pago ha sido confirmado y procesado por la red de finanzas abiertas.
`FAILED`	El pago ha sido rechazado por el usuario, el usuario no ha proporcionado consentimiento para el pago, o ha habido un error general en la red de finanzas abiertas.

`STATUS_UPDATE` webhook al usar enlaces de pago

También recibirás webhooks STATUS_UPDATE al usar enlaces de pago. Por favor, consulta el artículo Proceso de pago del widget de nuestros pagos de entrada OFPI para obtener información detallada sobre cuándo se envía cada evento de webhook.

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "SUCCEEDED",
    "end_to_end_id": "E432158152024081610416f2b595b056",
    "metadata": {"internal_reference_id": "GGq12345w2"}
  },
}

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "The payment consent was not accepted in time.",
    "end_to_end_id": "E432158152024081610416f2b595b056",
  }
}

Una vez que recibas la notificación, puedes obtener detalles sobre la intención de pago haciendo la siguiente solicitud:

curl --request GET 'https://api.belvo.com/payments/br/payment-intents/{id}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Donde:

id es el object_id de la intención de pago (que recibes en el evento de webhook).

Códigos de falla y mensajes

A continuación se muestra una lista de failure_codes y failure_messages que puedes recibir en un webhook de Payment Intents cuando un cargo falla:

Código	Mensaje	Cuándo puede ocurrir
`AMOUNT_OVER_LIMIT`	El monto del pago o el número de pagos excede los límites establecidos por la institución.	Actualización de Estado
`AUTHORIZATION_EXPIRED`	El tiempo de autorización ha expirado.	Actualización de Estado
`CONSENT_PENDING_AUTHORIZATION`	Consentimiento pendiente de autorización de múltiples niveles (estado 'PARTIALLY_ACCEPTED')."	Actualización de Estado
`HOLDER_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del titular de la cuenta.	Actualización de Estado
`ICP_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del ICP (Infraestructura de Claves Públicas)."	Actualización de Estado
`INSUFFICIENT_FUNDS`	La cuenta tiene fondos insuficientes para realizar el pago.	Actualización de Estado
`INVALID_CHARGE`	El cargo es inválido o incorrecto.	Actualización de Estado
`INVALID_PAYMENT_DETAIL`	Los detalles de pago proporcionados son inválidos.	Actualización de Estado
`NOT_INFORMED`	No se proporcionó una razón de error por parte de la institución.	Al Crear
`PAYMENT_CONSENT_MISMATCH`	Los detalles de pago no coinciden con el consentimiento proporcionado.	Al Crear
`PAYMENT_REFUSED_BY_HOLDER`	El pago fue rechazado por el titular de la cuenta.	Al Crear, Actualización de Estado
`PAYMENT_REFUSED_BY_SPI`	El pago fue rechazado por el SPI (Sistema de Pagamentos Instantâneos).	Actualización de Estado
`PAYMENT_SCHEDULING_FAILURE`	Hubo una falla al programar el pago.	Actualización de Estado
`RECEIVING_PSP_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del PSP receptor (Proveedor de Servicios de Pago).	Actualización de Estado
`SAME_ORIGIN_DESTINATION_ACCOUNTS`	Las cuentas de origen y destino son las mismas.	Actualización de Estado
`SPI_INFRASTRUCTURE_FAILURE`	Hubo una falla en la infraestructura del SPI.	Actualización de Estado
`SPI_REJECTED_PAYMENT`	Pago rechazado en el Sistema de Pagos Instantáneos (SPI).	Actualización de Estado
`USER_REJECTED`	El usuario rechazó la autorización del consentimiento.	Actualización de Estado

Transacciones

OBJECT_CREATED

Cada vez que se crea una nueva transacción, recibirás el siguiente webhook:

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "data": {
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "end_to_end_id": "E432158152024081610416f2b595b056",
  },
}

Una vez que recibas la notificación, puedes obtener detalles de la transacción haciendo la siguiente solicitud:

curl --request GET 'https://api.belvo.com/payments/br/transactions/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Donde:

id es el object_id de la transacción (que recibes en el evento del webhook).

Webhooks de Pagos (Brasil)

Configurar webhooks

Tipos de webhook

Direcciones IP de salida del webhook

Mejores prácticas para la respuesta del webhook del lado del cliente

Política de reintento de webhook

Cargos

STATUS_UPDATE

Códigos de falla y mensajes

Clientes

OBJECT_CREATED

Inscripciones

STATUS_UPDATE

Intenciones de pago

STATUS_UPDATE

Códigos de falla y mensajes

Transacciones

OBJECT_CREATED

¿Qué tan útil fue esta página?