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.
Você pode usar serviços como Webhook.site ou Pipedream para criar endpoints temporários para testes.
Para configurar sua URL de webhook:
- Faça login no seu Portal de Débito Direto. (Login Sandbox | Login Produção)
- Vá para Desenvolvedores -> Webhooks. (Webhooks Sandbox | Webhooks Produção)
- Insira sua URL.
- Clique em Set.
✅ Sua URL de webhook foi adicionada com 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
}
}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. |
| string | Se o status for Para detalhes sobre o |
| string | Se o status for Para detalhes sobre o |
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.
| 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. |
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).
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.
Quando você receber um webhook da Belvo, certifique-se de responder com um código de status 2XX (por exemplo, um 200). Veja nossa Política de Retentativas para saber quais falhas nós tentamos novamente.
Nós tentamos novamente a entrega de um webhook apenas quando o seu servidor está inacessível, expira o tempo de resposta, ou responde com um código de status HTTP 5xx. Nesses casos, tentamos novamente a cada 60 minutos por até 3 tentativas (a entrega inicial mais 2 retentativas).
Nós não tentamos novamente respostas HTTP 4xx (por exemplo, 400, 404, ou 418). Essas são tratadas como erros do cliente e o webhook não é enviado novamente.
Por exemplo, se a primeira tentativa falhar com um 503, nosso sistema espera 60 minutos antes de tentar novamente, e continua até receber uma resposta 2XX ou atingir o máximo de 2 retentativas.
Alguns serviços de teste (incluindo a resposta padrão do webhook.site) retornam 418. Esse é um status 4xx, então a Belvo não tentará novamente. Configure o endpoint de teste para retornar 2XX se você quiser confirmar a entrega bem-sucedida.