# 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 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.


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 V1 (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 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.

Terminologia de Campos V1 vs V2
Os payloads de webhook fornecem detalhes de erro usando nomes de campos diferentes, dependendo da versão do esquema do webhook e do recurso:

- **Webhooks V1 (CHARGES, CUSTOMERS, ENROLLMENTS, PAYMENT_INTENTS, TRANSACTIONS):** Usam `failure_code` (em `minúsculas`) e `failure_message` no objeto `data`.
- **Webhooks V2 (BANK_ACCOUNT, CHARGE, CUSTOMER, PAYMENT_AUTHORIZATION):** Formato de payload mínimo - recupere detalhes completos, incluindo `status_reason_code` e `status_reason_message` via solicitação GET.


Para uma tabela abrangente de todos os possíveis códigos de motivo de status, consulte Códigos e Mensagens de Pagamentos Brasil.

## Eventos de Webhook (Versão 2)

Versão do Schema 2 vs Versão 1
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 2 do Schema mostrado abaixo. Sem este cabeçalho, você receberá o formato V1 documentado na seção Eventos de Webhook (V1).

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 de webhook).


## Eventos de Webhook (V1)

Payment Intents
```json Exemplo de Webhook de Payment Intents
{
  "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"
  }
}
```

Payment Intents (chave Pix inválida)
```json Exemplo de Webhook de Payment Intents (chave Pix inválida)
{
  "webhook_id": "0e42a7b9-7b7a-4493-92f7-8285cae08b46",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "07f9fa2f-242a-4901-ab39-b244ca67adb6",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f74",
  "data": {
    "status": "FAILED",
    "metadata": {
      "internal_reference_id": "GGq73487w3"
    },
    "failure_code": "invalid_pix_key",
    "failure_message": "A chave Pix fornecida é inválida."
  }
}
```

Enrollments
```json Exemplo de Webhook de Enrollments
{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "f948c61d-e156-45df-923e-614faef2b2a9",
  "external_id": "ad930710-e5e1-47a6-957b-0df06deca34e",
  "data": {
    "status": "FAILED",
    "status_reason_code": "REJECTED_MANUALLY",
    "status_reason_message": "Cancelamento manual, explicitamente a pedido do usuário.",
    "details": {
      "status": "REJECTED"
    }
  }
}
```

| Parâmetro  | Obrigatório | Tipo | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `webhook_id` | true | string | O ID do webhook da Belvo. | `aadf41a1fc8e4f79a49f7f04027ac999` |
| `webhook_type` | true | string | O recurso ao qual este webhook se refere. | `CHARGES` |
| `webhook_code` | true | string | O evento que disparou o webhook. | `STATUS_UPDATE` |
| `object_id` | true | string | O ID do objeto ao qual este webhook se refere. | `d2e40773-19f6-48d1-93c3-3590ec0c74df` |
| `external_id` | true | 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` | true | 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` | false | string | O status da cobrança ou intenção de pagamento. | `FAILED` |
| `data.status_reason_code` | false | string | Um código de erro padronizado (em formato `UPPERCASE`) que indica por que o status de um recurso mudou. Aplicável apenas a webhooks de ENROLLMENTS em eventos V1. | `REJECTED_MANUALLY` |
| `data.status_reason_message` | false | string | Uma descrição legível que explica a mudança de status. Fornece contexto para o `status_reason_code`. Aplicável apenas a webhooks de ENROLLMENTS em eventos V1. | `Cancelamento manual, explicitamente a pedido do usuário.` |
| `data.failure_code` | false | string | No caso de falha da cobrança ou intenção de pagamento, um código único para o erro (em formato `lowercase` para Payment Intents e Charges). Por exemplo, `consent_expired` ou `invalid_pix_key` quando a chave Pix do beneficiário é inválida. | `invalid_pix_key` |
| `data.failure_message` | false | string | No caso de falha da cobrança ou intenção de pagamento, uma descrição legível do erro. | `A chave Pix fornecida é inválida.` |
| `data.end_to_end_id` | false | string | O ID do pagamento no sistema de pagamentos do Brasil. | `E432158152024081610416f2b595b056` |
| `data.metadata` | false | 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` | Um novo cliente foi criado (esquema V1). Ou seja, quando o cliente é criado de forma assíncrona e não como resultado de uma chamada direta POST. |
| ENROLLMENTS | `STATUS_UPDATE` | Há uma atualização no status de um Enrollment:- `PENDING` (O enrollment está aguardando o envio de detalhes biométricos.)
- `SUCCEEDED` (O enrollment foi aceito pela instituição.)
- `FAILED` (O enrollment foi rejeitado pela instituição.)

 |
| PAYMENT_INTENTS | `STATUS_UPDATE` | Há uma atualização no status de uma Payment Intent:- `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, houve um erro geral na rede de open finance, ou a chave Pix do beneficiário é inválida (`failure_code`: `invalid_pix_key`, `failure_message`: `A chave Pix fornecida é inválida.`).)

 |
| TRANSACTIONS | `OBJECT_CREATED` | Uma nova transação foi 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 (Charges)
```shell Exemplo (Charges)
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 de webhook).


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

Códigos Completos de Motivo de Status
Para a tabela completa de todos os valores de `status_reason_code` e suas mensagens correspondentes, consulte Códigos e Mensagens de Pagamentos Brasil. A tabela abaixo mostra um subconjunto de códigos comuns que podem aparecer em notificações de webhook.

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

| Código de Motivo de Status  | Mensagem de Motivo de Status | 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 |
| `invalid_pix_key` | A Chave Pix fornecida é inválida. | Payment Intents `STATUS_UPDATE` (V1 `failure_code` / `failure_message` no objeto `data`) |
| `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 |