# 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. Serviços de Webhook Você pode usar serviços como Webhook.site ou Pipedream para criar endpoints temporários para testes. ## 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", "amount": 100.5, "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", "amount": 100.5, "failedReason": "01", "failedMessage": "Cuenta inexistente" } } ``` Exemplo de Payload do Webhook (Validação de Centavos Sucesso) ```json Exemplo de Payload do Webhook (Validação de Centavos Sucesso) { "eventType": "payment_method_update", "eventCode": "payment_method_registration_successful", "datetime": "2022-01-01T12:34:56.789Z", "details": { "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", "reference": "your_reference_here", "status": "active", "failedReason": null, "failedMessage": null } } ``` Exemplo de Payload do Webhook (Validação de Centavos Falha) ```json Exemplo de Payload do Webhook (Validação de Centavos Falha) { "eventType": "payment_method_update", "eventCode": "payment_method_registration_failed", "datetime": "2022-01-01T12:34:56.789Z", "details": { "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", "reference": "your_reference_here", "status": "error", "failedReason": "account_validation_failed", "failedMessage": "Account owner validation was not successful" } } ``` 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" } } ``` Exemplo de Payload do Webhook (Consentimento) ```json Exemplo de Payload do Webhook (Consentimento) { "eventType": "consent_update", "eventCode": "consent_submitted", "datetime": "2025-10-30T12:34:56.789Z", "details": { "id": "550e8400-e29b-41d4-a716-446655440000", "paymentMethodId": "660e8400-e29b-41d4-a716-446655440000", "status": "submitted" } } ``` Exemplo de Payload do Webhook (Retirada) ```json Exemplo de Payload do Webhook (Retirada) { "eventType": "withdrawal_update", "eventCode": "withdrawal_created", "datetime": "2022-01-01T12:34:56.789Z", "details": { "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", "fromDatetime": "2022-01-01T00:00:00.000Z", "toDatetime": "2022-01-01T23:59:59.999Z", "extra": {} } } ``` Resultados da Validação de Centavos O resultado de uma validação de centavos é entregue através dos webhooks de registro de método de pagamento. Uma validação bem-sucedida envia `payment_method_registration_successful` (o método de pagamento se torna `active`), enquanto uma validação falha envia `payment_method_registration_failed` com um `failedReason` de `account_validation_failed`. Para mais informações, consulte nosso guia dedicado de Validação de Centavos. | Parâmetro | Tipo | Descrição | | --- | --- | --- | | `eventType` | string | O tipo do evento do recurso da API. Pode ser um dos: `consent_update`, `customer_update`, `payment_method_update`, `payment_request_update` ou `withdrawal_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, Solicitação de Pagamento ou Retirada) 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.amount` | number | O valor da solicitação de pagamento. Este campo está presente para todos os códigos de evento de payment_request. | | `details.failedReason` | string | Se o status for `failed` ou `canceled`, este campo contém um código de falha. Este campo é `null` se o `status` não for `failed` ou `canceled`. Para detalhes sobre o `failedReason` e `failedMessage` esperados (incluindo a lista de valores possíveis), consulte nosso guia de Erros Bancários de Débito Direto. | | `details.failedMessage` | string | Se o status for `failed` ou `canceled`, este campo contém uma descrição da falha. Este campo é `null` se o `status` não for `failed` ou `canceled`. Para detalhes sobre o `failedReason` e `failedMessage` esperados (incluindo a lista de valores possíveis), consulte nosso guia de Erros Bancários de Débito Direto. | | `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.** | | `details.paymentMethodId` | string | Se o evento estiver relacionado a um consentimento, este campo contém o ID do método de pagamento associado. **Este campo está disponível apenas para eventos relacionados a consentimento.** | | `details.fromDatetime` | string | Se o evento estiver relacionado a uma retirada, este campo contém o timestamp ISO-8601 do início do período de liquidação. **Este campo está disponível apenas para eventos relacionados a retirada.** | | `details.toDatetime` | string | Se o evento estiver relacionado a uma retirada, este campo contém o timestamp ISO-8601 do final do período de liquidação. **Este campo está disponível apenas para eventos relacionados a retirada.** | | `details.extra` | object | Se o evento estiver relacionado a uma retirada, este campo contém informações adicionais sobre a retirada. **Este campo está disponível apenas para eventos relacionados a retirada.** | 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. Este webhook é enviado globalmente para todos os comerciantes, mesmo que eles não tenham o cliente bloqueado registrado, já que a lista de bloqueio é compartilhada entre todos os comerciantes. | | 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. | | Consentimentos | `consent_update` | `consent_submitted` | todos os documentos necessários foram enviados para o consentimento. | | Consentimentos | `consent_update` | `consent_confirmed` | o consentimento foi aprovado e agora está ativo. | | Consentimentos | `consent_update` | `consent_incomplete_information` | documentos estão faltando ou são inválidos para o consentimento. | | Consentimentos | `consent_update` | `consent_rejected` | o consentimento foi negado. | | 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 foi relatado pelo provedor de infraestrutura de pagamento. | | Solicitações de Pagamento | `payment_request_update` | `payment_request_chargeback` | um chargeback foi feito pelo seu cliente. | | Saques | `withdrawal_update` | `withdrawal_created` | um saque foi criado e os fundos estão sendo liquidados para o comerciante. | Notificações Globais de Bloqueio de Clientes Quando um cliente é bloqueado devido a um chargeback, **todos os comerciantes recebem o webhook `customer_blocked`**, independentemente de terem ou não esse cliente registrado. Isso ocorre porque a Belvo mantém uma lista de bloqueio global compartilhada entre todos os comerciantes para proteger todo o ecossistema de atividades fraudulentas. O payload do webhook inclui o `documentNumber` (RFC ou CURP) do cliente bloqueado para que você possa verificar se o cliente existe no seu sistema e tomar as medidas apropriadas. O webhook `customer_blocked` é enviado apenas uma vez para cada comerciante (ou seja, se você já recebeu um e um novo chargeback ocorrer para o mesmo cliente, mas para outro comerciante, você não receberá outro webhook para esse cliente). Notas de Status de Webhook de Consentimento O sistema envia notificações de webhook sempre que o status de um consentimento muda para permitir o acompanhamento em tempo real do ciclo de vida do consentimento. Nenhum webhook é enviado para o status inicial `awaiting_information`. Se configurado, os webhooks de consentimento incluem um cabeçalho `Authorization` com o segredo do webhook do comerciante para verificação segura. ## 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 Retentativa Quando a Belvo não recebe uma resposta `2XX` do seu servidor, tentamos reenviar o webhook a cada 60 minutos por até 3 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 2 retentativas.