Webhooks de Pagos (Brasil)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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

Configurar webhooks

Para configurar un nuevo webhook:

1. En tu panel de control de Belvo, ve a la sección de webhooks de pagos.

2. En la pestaña de Payments Webhooks, haz clic en +New webhook.

   

3. 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.

4. Haz clic en Create webhook.

   

Esquemas y Tipos de Webhook

Belvo ofrece dos versiones de esquemas de webhook para los webhooks de Payments Brazil:

• Schema Version 1 (Legacy): El formato original de webhook utilizado para los webhooks de CHARGES, PAYMENT_INTENTS y TRANSACTIONS. Este esquema sigue funcionando para integraciones existentes.
• Schema Version 2 (New): Un formato de webhook más reciente introducido para una funcionalidad mejorada. Este esquema se utiliza para los webhooks de BANK_ACCOUNTS (V2), CUSTOMERS (V2) y PAYMENT_AUTHORIZATIONS.

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

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 enviar la solicitud nuevamente automáticamente. 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.

Eventos de Webhook (Versión 2)

Cada vez que haya un evento relacionado con una Cuenta Bancaria, Cargo, Cliente o Autorización de Pago, recibirás el siguiente webhook:

{
  "schema_version": "2",
  "resource": "BANK_ACCOUNT",
  "resource_id": "7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b",
  "resource_version": "v2",
  "timestamp": "2025-01-16T10:30:45.123456Z"
}

Donde:

Una vez que recibas la notificación, tendrás que obtener los detalles del recurso haciendo la siguiente solicitud:

curl --request GET 'https://api.belvo.com/payments/br/{resource}/{id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2'

Donde:

• resource es el tipo de recurso que deseas obtener (bank-accounts, charges, customers, o payment-authorizations).
• id es el resource_id de la cuenta bancaria (que recibes en el evento del webhook).

Eventos de Webhook (Legacy)

{
  "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",
  }
}

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.

Una vez que recibas la notificación, tendrás que obtener detalles del recurso haciendo la siguiente solicitud:

curl --request GET 'https://api.belvo.com/payments/br/{resource}/{id}/' \
  -u SECRET_ID:SECRET_PASSWORD \

Donde:

• resource es el tipo de recurso que deseas recuperar (bank-accounts, charges, customers, payment-intents, o transactions).
• id es el object_id del recurso (que recibes en el evento del webhook).

Códigos y Mensajes de Error

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