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 painel do Belvo, vá para a seção de webhooks de pagamento.

2. Na aba Payments Webhooks, clique em +New webhook.

   

3. Preencha o formulário de New 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 Create webhook.

   

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 tentativas de Webhook

Se o nosso sistema não receber um código de status 2XX, ele tentará automaticamente enviar a solicitação novamente. Este processo de repetição 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é que receba uma resposta bem-sucedida ou atinja o máximo de três tentativas.

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": "The payment consent was not accepted in time.",
    "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, você precisará 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 do 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: