Skip to content
Last updated

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

Este artigo é sobre webhooks para nossa solução de Iniciação de Pagamentos. Para informações sobre nossos webhooks de Agregação e Enriquecimento, confira este artigo

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 (Legado): O formato original de webhook usado para webhooks de CHARGES, PAYMENT_INTENTS e TRANSACTIONS. Este esquema continua a funcionar para integrações existentes.
  • Versão de Esquema 2 (Novo): Um formato de webhook mais recente introduzido para funcionalidade aprimorada. Este esquema é usado para webhooks de BANK_ACCOUNTS (V2), CUSTOMERS (V2) e PAYMENT_AUTHORIZATIONS.
Requisitos da Versão de Esquema 2

Os webhooks da Versão de Esquema 2 são enviados apenas quando os recursos são criados usando o cabeçalho X-Belvo-API-Resource-Version: Payments-BR.V2. Se você não incluir este cabeçalho, receberá webhooks no formato legado (quando aplicável).

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

Recomendamos fortemente que você coloque esses endereços IP na lista de permissões para que possa receber eventos de webhook.

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á enviar a solicitação novamente automaticamente. Este processo de tentativa 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)

Versão do Schema 2 vs Legado

Webhooks de Conta Bancária, Cobrança e Cliente estão disponíveis em ambas as versões de schema. Ao usar o cabeçalho X-Belvo-API-Resource-Version: Payments-BR.V2, você receberá o novo formato da Versão do Schema 2 mostrado abaixo. Sem este cabeçalho, você receberá o formato legado documentado na seção Clientes (Legado).

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

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

Onde:

Parâmetro ObrigatórioTipoDescriçãoExemplo
schema_versionsimstringA versão do schema do webhook. Atualmente, isso será sempre 2.2
resourcesimstringO tipo de recurso ao qual este webhook se refere. Pode ser um dos seguintes: BANK_ACCOUNT, CHARGE, CUSTOMER, PAYMENT_AUTHORIZATION.BANK_ACCOUNT
resource_idsimstringO identificador único do recurso. Você pode usar este ID para recuperar os detalhes do recurso.7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b
resource_versionsimstringA versão da API usada ao criar o recurso.v2
timestampsimdate-timeO timestamp ISO-8601 de quando o recurso foi atualizado pela última vez.2025-01-16T10:30:45.123456Z

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

Formato da 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 do webhook).

Eventos de Webhook (Legado)

{
  "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 ObrigatórioTipoDescriçãoExemplo
webhook_idsimstringO ID do webhook da Belvo.aadf41a1fc8e4f79a49f7f04027ac999
webhook_typesimstringO recurso ao qual este webhook se refere.CHARGES
webhook_codesimstringO evento que acionou o webhook.STATUS_UPDATE
object_idsimstringO ID do objeto ao qual este webhook se refere.d2e40773-19f6-48d1-93c3-3590ec0c74df
external_idsimstringO identificador único que você forneceu ao criar o objeto. Para cobranças e transações, este campo sempre retornará null.c3c51aaf-aaa3-400c-926d-87ab62e195fd
datasimobjectUm objeto contendo dados específicos sobre o evento. Os campos retornados neste objeto dependem do webhook_type e webhook_code.Veja as linhas seguintes.
data.statusnãostringO status da cobrança ou intenção de pagamento.FAILED
data.failure_codenãostringNo caso de a cobrança ou intenção de pagamento falhar, um código único para o erro.consent_expired
data.failure_messagenãostringNo caso de a cobrança ou intenção de pagamento falhar, uma descrição legível do erro.The payment consent was not accepted in time.
data.end_to_end_idnãostringO ID do pagamento no sistema de pagamentos do Brasil.E432158152024081610416f2b595b056
data.metadatanãoobjectSe você forneceu alguma informação no objeto metadata ao criar seu pagamento, ela será incluída no corpo do webhook.{ "internal_reference_id": "GGq12345w2" }

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

TipoEvento Enviado sempre que...
CHARGESSTATUS_UPDATEHá uma atualização no status de uma Cobrança:
  • SCHEDULED (A cobrança está 'pausada' até a data de pagamento agendada.)
  • SUCCEEDED (A cobrança foi confirmada e processada pela rede de open finance.)
  • FAILED (O usuário não forneceu consentimento para o pagamento, ou houve um erro geral na rede de open finance.)
  • CANCELED (A cobrança agendada foi cancelada.)
CUSTOMERSOBJECT_CREATEDHá um novo cliente criado (Esquema legado). Ou seja, quando o cliente é criado de forma assíncrona e não como resultado de uma chamada POST direta.
ENROLLMENTSSTATUS_UPDATEHá uma atualização no status de uma Inscrição:
  • PENDING (A inscrição está aguardando o envio de detalhes biométricos.)
  • SUCCEEDED (A inscrição foi aceita pela instituição.)
  • FAILED (A inscrição foi rejeitada pela instituição.)
PAYMENT_INTENTSSTATUS_UPDATEHá uma atualização no status de uma Intenção de Pagamento:
  • REQUIRES_PAYMENT_METHOD (Detalhes adicionais são necessários para completar o fluxo de intenção de pagamento.)
  • REQUIRES_ACTION (Você enviou confirm=true no fluxo de intenção de pagamento e a Belvo agora inicia o fluxo de pagamento na rede de open finance.)
  • PROCESSING (O pagamento está sendo processado na rede de open finance.)
  • SCHEDULED (O pagamento está 'pausado' até a data de pagamento agendada.)
  • CANCELED (A intenção de pagamento agendada foi cancelada.)
  • SUCCEEDED (O pagamento foi confirmado e processado pela rede de open finance.)
  • FAILED (O pagamento foi rejeitado pelo usuário, o usuário não forneceu consentimento para o pagamento, ou houve um erro geral na rede de open finance.)
TRANSACTIONSOBJECT_CREATEDHá uma nova transação criada.

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

Formato da 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 e Mensagens de Falha

Abaixo está uma lista de failure_codes e failure_messages que você pode receber em um webhook de Charge ou Payment Intents:

Código MensagemQuando pode ocorrer
AMOUNT_OVER_LIMITO valor do pagamento ou o número de pagamentos excede os limites estabelecidos pela instituição.Atualização de Status
AUTHORIZATION_EXPIREDO tempo de autorização expirou.Atualização de Status
CONSENT_PENDING_AUTHORIZATIONConsentimento pendente de autorização de múltiplos níveis (status 'PARTIALLY_ACCEPTED').Atualização de Status
HOLDER_INFRASTRUCTURE_FAILUREHouve uma falha na infraestrutura do titular da conta.Atualização de Status
ICP_INFRASTRUCTURE_FAILUREHouve uma falha na infraestrutura do ICP (Infraestrutura de Chaves Públicas).Atualização de Status
INSUFFICIENT_FUNDSA conta não possui fundos suficientes para realizar o pagamento.Atualização de Status
INVALID_CHARGEA cobrança é inválida ou incorreta.Atualização de Status
INVALID_PAYMENT_DETAILOs detalhes do pagamento fornecidos são inválidos.Atualização de Status
NOT_INFORMEDNenhuma razão de erro foi fornecida pela instituição.Na Criação
PAYMENT_CONSENT_MISMATCHOs detalhes do pagamento não correspondem ao consentimento fornecido.Na Criação
PAYMENT_REFUSED_BY_HOLDERO pagamento foi recusado pelo titular da conta.Na Criação, Atualização de Status
PAYMENT_REFUSED_BY_SPIO pagamento foi recusado pelo SPI (Sistema de Pagamentos Instantâneos).Atualização de Status
PAYMENT_SCHEDULING_FAILUREHouve uma falha no agendamento do pagamento.Atualização de Status
RECEIVING_PSP_INFRASTRUCTURE_FAILUREHouve uma falha na infraestrutura do PSP (Provedor de Serviços de Pagamento) receptor.Atualização de Status
SAME_ORIGIN_DESTINATION_ACCOUNTSAs contas de origem e destino são as mesmas.Atualização de Status
SPI_INFRASTRUCTURE_FAILUREHouve uma falha na infraestrutura do SPI.Atualização de Status
SPI_REJECTED_PAYMENTPagamento rejeitado no Sistema de Pagamentos Instantâneos (SPI).Atualização de Status
USER_REJECTEDO usuário rejeitou a autorização do consentimento.Atualização de Status