# Payments Webhooks (Brazil)

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:


```json 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ó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:

Formato da Solicitação

```shell 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'
```

Exemplo (Contas Bancárias)

```shell Exemplo (Contas Bancárias)
curl --request GET 'https://api.belvo.com/payments/br/bank-accounts/{id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2'
```

Exemplo (Cobranças)

```shell Exemplo (Cobranças)
curl --request GET 'https://api.belvo.com/payments/br/charges/{id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2'
```

Exemplo (Autorizações de Pagamento)

```shell Exemplo (Autorizações de Pagamento)
curl --request GET 'https://api.belvo.com/payments/br/payment-authorizations/{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)


```json
{
  "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:- `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.)

 |
| 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:- `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_INTENTS | `STATUS_UPDATE` | Há 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.)

 |
| 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:

Formato da Solicitação

```shell Formato da Solicitação
curl --request GET 'https://api.belvo.com/payments/br/{resource}/{id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
```

Exemplo (Cobranças)

```shell Exemplo (Cobranças)
curl --request GET 'https://api.belvo.com/payments/br/charges/{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_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 |