Payments Webhooks (Brazil)

Copiar

• Copiar para LLM

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

  Abrir esta página como Markdown
• Abrir no ChatGPT

  Obter insights do ChatGPT
• Abrir no Claude

  Obter insights do Claude
• Conectar ao Cursor

  Instalar servidor MCP no Cursor
• Conectar ao VS Code

  Instalar servidor MCP no VS Code

Um webhook é um retorno de chamada web que a Belvo usa para enviar notificações sobre um link específico.

Configurar webhooks

Para configurar um novo webhook:

1. No seu dashboard da Belvo, vá para a seção de webhooks de pagamento.

2. Na aba Webhooks de Pagamentos, clique em +Novo webhook.

   

3. Preencha o formulário de Novo webhook com as informações necessárias.

   • URL: a URL para receber as notificações do webhook.
   • Authorization: um token bearer opcional para usar se sua URL estiver protegida.

4. Clique em Criar webhook.

   

5. Para registrar URLs de webhook adicionais, repita os passos 2-4 para cada URL que você deseja adicionar.

Múltiplas URLs de Webhook

Você pode registrar múltiplas URLs de webhook para sua organização. Quando múltiplas URLs são registradas, todas as URLs de webhook registradas receberão a mesma notificação de evento para cada evento de webhook. Isso permite que você envie notificações para diferentes sistemas ou ambientes simultaneamente.

Esquemas e Tipos de Webhook

A Belvo oferece duas versões de esquema de webhook para webhooks de Pagamentos Brasil:

• Versão de Esquema 1: O formato original de webhook usado para webhooks de CHARGES, ENROLLMENTS, PAYMENT_INTENTS e TRANSACTIONS. Este esquema continua a funcionar para integrações existentes.
• Versão de Esquema 2 (Nova): Um formato de webhook mais recente introduzido para funcionalidade aprimorada. Este esquema é usado para webhooks de BANK_ACCOUNTS (V2), CUSTOMERS (V2) e PAYMENT_AUTHORIZATIONS.

Endereços IP de saída do webhook

Você pode receber eventos de webhook dos seguintes endereços IP:

• 3.130.254.46
• 18.220.61.186
• 18.223.45.212

Melhor prática de resposta de webhook no lado do cliente

Recomendamos fortemente que, assim que você receber um webhook, responda à Belvo com um código de status 2XX dentro de cinco segundos para confirmar que você recebeu o webhook. Caso contrário, nossa API tentará novamente a solicitação.

Política de reintento de webhook

Se nosso sistema não receber um código de status 2XX, ele tentará enviar a solicitação novamente automaticamente. Este processo de reintento ocorrerá até três vezes, com cada tentativa espaçada por 60 segundos. Por exemplo, se a primeira tentativa falhar, nosso sistema espera 60 segundos antes de tentar novamente e continuará esse padrão até receber uma resposta bem-sucedida ou atingir o máximo de três reintentos.

Eventos de Webhook (Versão 2)

Sempre que houver um evento relacionado a uma Conta Bancária, Cobrança, Cliente ou Autorização de Pagamento, você receberá o seguinte webhook:

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

Onde:

Assim que você receber a notificação, terá que obter os detalhes do recurso fazendo a seguinte solicitação:

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'

Onde:

• resource é o tipo de recurso que você deseja recuperar (bank-accounts, charges, customers, ou payment-authorizations).
• id é o resource_id da conta bancária (que você recebe no evento de 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": "O consentimento de pagamento não foi aceito a tempo.",
    "end_to_end_id": "E432158152024081610416f2b595b056"
  }
}

Para informações sobre os dados específicos de um determinado webhook, clique no tipo de webhook na tabela abaixo.

Assim que você receber a notificação, será necessário obter detalhes do recurso fazendo a seguinte solicitação:

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

Onde:

• resource é o tipo de recurso que você deseja recuperar (bank-accounts, charges, customers, payment-intents, ou transactions).
• id é o object_id do recurso (que você recebe no evento de webhook).

Códigos de Motivo de Status (Legado: Códigos de Falha)

Abaixo está uma lista de códigos de motivo de status comuns e mensagens que você pode receber em notificações de webhook V1: