Webhooks de Pagos (Brasil)

Copiar

• Copiar para LLM

  Copiar página como Markdown para LLMs
• Ver como Markdown

  Abrir esta página como Markdown
• Abrir en ChatGPT

  Obtener información de ChatGPT
• Abrir en Claude

  Obtener información de Claude
• Conectar a Cursor

  Instalar servidor MCP en Cursor
• Conectar a VS Code

  Instalar servidor MCP en VS Code

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:

• Versión de Esquema 1: El formato original de webhook utilizado para los webhooks de CHARGES, ENROLLMENTS, PAYMENT_INTENTS y TRANSACTIONS. Este esquema sigue funcionando para integraciones existentes.
• Versión de Esquema 2 (Nuevo): 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 automáticamente enviar la solicitud nuevamente. Este proceso de reintento ocurrirá hasta tres veces, con cada intento espaciado 60 segundos. Por ejemplo, si el primer intento falla, nuestro sistema espera 60 segundos antes de intentar nuevamente y continuará 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 Bank Account, Charge, Customer o Payment Authorization 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 recuperar (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 (V1)

{
  "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 de Razón de Estado (Legado: Códigos de Fallo)

A continuación se muestra una lista de códigos de razón de estado comunes y mensajes que puedes recibir en notificaciones de webhook V1: