# Webhooks de Pagamento (México)

Um **webhook** é um retorno de chamada web que a Belvo usa para enviar notificações sobre um link específico. Você precisará configurar webhooks para usar as APIs da Belvo.

## Configurando seus webhooks

Para configurar sua URL de webhook:

1. Faça login no seu Portal de Débito Direto. (Login Sandbox | Login Produção)
2. Vá para Desenvolvedores -> Webhooks. (Webhooks Sandbox | Webhooks Produção)
3. Insira sua URL.
4. Clique em **Set**.


✅ Sua URL de webhook foi adicionada com sucesso.

## Payload do Webhook

Exemplo de Payload do Webhook (Sucesso)

```json Exemplo de Payload do Webhook (Sucesso)
{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "successful",
    "failedReason": null,
    "failedMessage": null
  }
}
```

Exemplo de Payload do Webhook (Falha)

```json Exemplo de Payload do Webhook (Falha)
{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "failed",
    "failedReason": "01",
    "failedMessage": "Cuenta inexistente"
  }
}
```

Exemplo de Payload do Webhook (Cliente)

```json Exemplo de Payload do Webhook (Cliente)
{
  "eventType": "customer_update",
  "eventCode": "customer_blocked",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "documentNumber": "RFC/CURP of Customer"
  }
}
```

| Parâmetro  | Tipo | Descrição |
|  --- | --- | --- |
| `eventType` | string | O tipo do evento do recurso da API. Pode ser um dos seguintes: `customer_update`, `payment_method_update` ou `payment_request_update`. |
| `eventCode` | string | O código do evento do webhook. Para detalhes sobre os valores possíveis, consulte a seção Códigos de Evento do Webhook abaixo. |
| `datetime` | string | O timestamp ISO-8601 quando o evento foi enviado. |
| `details` | object | Um objeto contendo dados específicos sobre o evento. |
| `details.id` | string | O ID Belvo do recurso da API (Cliente, Método de Pagamento ou Solicitação de Pagamento) ao qual o evento está relacionado. |
| `details.reference` | string | Se você forneceu uma `reference` ao criar o recurso, uma descrição opcional do objeto. |
| `details.status` | string | O status do recurso. |
| `details.failedReason`
 | string
 | Se o status for `failed`, este campo contém um código de falha. Este campo é `null` se o `status` não for `failed`.
Para detalhes sobre o `failedReason` e `failedMessage` esperados (incluindo a lista de valores possíveis), consulte nosso guia de Erros de Débito Direto Bancário.
 |
| `details.failedMessage`
 | string
 | Se o status for `failed`, este campo contém uma descrição da falha. Este campo é `null` se o `status` não for `failed`.
Para detalhes sobre o `failedReason` e `failedMessage` esperados (incluindo a lista de valores possíveis), consulte nosso guia de Erros de Débito Direto Bancário.
 |
| `details.documentNumber` | string | Se o evento estiver relacionado a um cliente, este campo contém o RFC ou CURP do cliente relacionado ao método de pagamento por débito direto. **Este campo está disponível apenas para eventos relacionados a clientes.** |


Para informações sobre payloads específicos para um determinado recurso da API e código de webhook, basta clicar no **Código do Evento** do webhook na tabela abaixo.

## Códigos de Evento de Webhook

| Recurso | Tipo de Evento  | Código de Evento  | Enviado sempre que... |
|  --- | --- | --- | --- |
| Clientes | `customer_update` | `customer_blocked` | o cliente relacionado ao método de pagamento por débito direto foi bloqueado devido a atividade suspeita. |
| Clientes | `customer_update` | `customer_unblocked` | o cliente relacionado ao método de pagamento por débito direto foi desbloqueado após revisão pelas partes relevantes. |
| Métodos de Pagamento | `payment_method_update` | `payment_method_registration_successful` | o registro do método de pagamento por débito direto foi bem-sucedido. |
| Métodos de Pagamento | `payment_method_update` | `payment_method_registration_failed` | o registro do método de pagamento por débito direto falhou. |
| Métodos de Pagamento | `payment_method_update` | `payment_method_registration_canceled` | o registro do débito direto foi cancelado (geralmente pelo proprietário). |
| Solicitações de Pagamento | `payment_request_update` | `payment_request_successful` | o pagamento foi bem-sucedido e recebemos confirmação do provedor de infraestrutura de pagamento. |
| Solicitações de Pagamento | `payment_request_update` | `payment_request_failed` | um erro é relatado pelo provedor de infraestrutura de pagamento. |
| Solicitações de Pagamento | `payment_request_update` | `payment_request_chargeback` | um chargeback foi feito pelo seu cliente. |


## Melhores Práticas

Quando você receber um webhook da Belvo, certifique-se de responder com um código de status 2XX (por exemplo, um `200`). Se o sistema da Belvo não receber uma resposta `200` do seu servidor, tentaremos automaticamente reenviar a solicitação. Para mais detalhes, consulte nossa seção de Política de Retentativas.

## Política de reintento

Quando a Belvo não recebe uma resposta `2XX` do seu servidor, tentamos enviar o webhook novamente a cada 60 minutos por até 10 tentativas.

Por exemplo, se a primeira tentativa (inicial) falhar, nosso sistema espera 60 minutos antes de tentar novamente e continuará nesse padrão até que receba uma resposta bem-sucedida ou atinja o máximo de 10 reintentos.