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
Para configurar um novo webhook:
No seu painel do Belvo, vá para a seção de webhooks de pagamento.
Na aba Payments Webhooks, clique em +New webhook.
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.
Clique em Create 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.
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).
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.
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.
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.
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:
{
"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ório | Tipo | Descrição | Exemplo |
---|---|---|---|---|
schema_version | sim | string | A versão do schema do webhook. Atualmente, isso será sempre 2 . | 2 |
resource | sim | string | O tipo de recurso ao qual este webhook se refere. Pode ser um dos seguintes: BANK_ACCOUNT , CHARGE , CUSTOMER , PAYMENT_AUTHORIZATION . | BANK_ACCOUNT |
resource_id | sim | string | O identificador único do recurso. Você pode usar este ID para recuperar os detalhes do recurso. | 7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b |
resource_version | sim | string | A versão da API usada ao criar o recurso. | v2 |
timestamp | sim | date-time | O 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:
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
oupayment-authorizations
).id
é oresource_id
da conta bancária (que você recebe no evento do webhook).
{
"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ório | Tipo | Descrição | Exemplo |
---|---|---|---|---|
webhook_id | sim | string | O ID do webhook da Belvo. | aadf41a1fc8e4f79a49f7f04027ac999 |
webhook_type | sim | string | O recurso ao qual este webhook se refere. | CHARGES |
webhook_code | sim | string | O evento que acionou o webhook. | STATUS_UPDATE |
object_id | sim | string | O ID do objeto ao qual este webhook se refere. | d2e40773-19f6-48d1-93c3-3590ec0c74df |
external_id | sim | string | O 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 |
data | sim | object | Um 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.status | não | string | O status da cobrança ou intenção de pagamento. | FAILED |
data.failure_code | não | string | No caso de a cobrança ou intenção de pagamento falhar, um código único para o erro. | consent_expired |
data.failure_message | não | string | No 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_id | não | string | O ID do pagamento no sistema de pagamentos do Brasil. | E432158152024081610416f2b595b056 |
data.metadata | não | object | Se 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.
Tipo | Evento | Enviado sempre que... |
---|---|---|
CHARGES | STATUS_UPDATE | Há uma atualização no status de uma Cobrança:
|
CUSTOMERS | OBJECT_CREATED | Há 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. |
ENROLLMENTS | STATUS_UPDATE | Há uma atualização no status de uma Inscrição:
|
PAYMENT_INTENTS | STATUS_UPDATE | Há uma atualização no status de uma Intenção de Pagamento:
|
TRANSACTIONS | OBJECT_CREATED | Há uma nova transação criada. |
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
, outransactions
).id
é oobject_id
do recurso (que você recebe no evento do webhook).
Abaixo está uma lista de failure_code
s e failure_message
s que você pode receber em um webhook de Charge ou Payment Intents:
Código | Mensagem | Quando pode ocorrer |
---|---|---|
AMOUNT_OVER_LIMIT | O valor do pagamento ou o número de pagamentos excede os limites estabelecidos pela instituição. | Atualização de Status |
AUTHORIZATION_EXPIRED | O tempo de autorização expirou. | Atualização de Status |
CONSENT_PENDING_AUTHORIZATION | Consentimento pendente de autorização de múltiplos níveis (status 'PARTIALLY_ACCEPTED'). | Atualização de Status |
HOLDER_INFRASTRUCTURE_FAILURE | Houve uma falha na infraestrutura do titular da conta. | Atualização de Status |
ICP_INFRASTRUCTURE_FAILURE | Houve uma falha na infraestrutura do ICP (Infraestrutura de Chaves Públicas). | Atualização de Status |
INSUFFICIENT_FUNDS | A conta não possui fundos suficientes para realizar o pagamento. | Atualização de Status |
INVALID_CHARGE | A cobrança é inválida ou incorreta. | Atualização de Status |
INVALID_PAYMENT_DETAIL | Os detalhes do pagamento fornecidos são inválidos. | Atualização de Status |
NOT_INFORMED | Nenhuma razão de erro foi fornecida pela instituição. | Na Criação |
PAYMENT_CONSENT_MISMATCH | Os detalhes do pagamento não correspondem ao consentimento fornecido. | Na Criação |
PAYMENT_REFUSED_BY_HOLDER | O pagamento foi recusado pelo titular da conta. | Na Criação, Atualização de Status |
PAYMENT_REFUSED_BY_SPI | O pagamento foi recusado pelo SPI (Sistema de Pagamentos Instantâneos). | Atualização de Status |
PAYMENT_SCHEDULING_FAILURE | Houve uma falha no agendamento do pagamento. | Atualização de Status |
RECEIVING_PSP_INFRASTRUCTURE_FAILURE | Houve uma falha na infraestrutura do PSP (Provedor de Serviços de Pagamento) receptor. | Atualização de Status |
SAME_ORIGIN_DESTINATION_ACCOUNTS | As contas de origem e destino são as mesmas. | Atualização de Status |
SPI_INFRASTRUCTURE_FAILURE | Houve uma falha na infraestrutura do SPI. | Atualização de Status |
SPI_REJECTED_PAYMENT | Pagamento rejeitado no Sistema de Pagamentos Instantâneos (SPI). | Atualização de Status |
USER_REJECTED | O usuário rejeitou a autorização do consentimento. | Atualização de Status |