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
}
}| Parâmetro | Tipo | Descrição |
|---|---|---|
eventType | string | O tipo do evento do recurso da API. Pode ser um dos seguintes: consent_update, 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 de 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.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 de 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. |
Para informações sobre payloads específicos para um determinado recurso da API e código de webhook, basta clicar no Código de Evento do webhook na tabela abaixo.
| Recurso | Tipo de Evento | Código de Evento | Enviado sempre que... |
|---|---|---|---|
| Customers | customer_update | customer_blocked | o usuário 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 usuário bloqueado registrado, já que a lista de bloqueio é compartilhada entre todos os comerciantes. |
| Customers | customer_update | customer_unblocked | o usuário relacionado ao método de pagamento por débito direto foi desbloqueado após revisão pelas partes relevantes. |
| Consents | consent_update | consent_submitted | todos os documentos necessários foram enviados para o consentimento. |
| Consents | consent_update | consent_confirmed | o consentimento foi aprovado e agora está ativo. |
| Consents | consent_update | consent_incomplete_information | documentos estão faltando ou são inválidos para o consentimento. |
| Consents | consent_update | consent_rejected | o consentimento foi negado. |
| Payment Methods | payment_method_update | payment_method_registration_successful | o registro do método de pagamento por débito direto foi bem-sucedido. |
| Payment Methods | payment_method_update | payment_method_registration_failed | o registro do método de pagamento por débito direto falhou. |
| Payment Methods | payment_method_update | payment_method_registration_canceled | o registro do débito direto foi cancelado (geralmente pelo proprietário). |
| Payment Requests | payment_request_update | payment_request_successful | o pagamento foi bem-sucedido e recebemos confirmação do provedor de infraestrutura de pagamento. |
| Payment Requests | payment_request_update | payment_request_failed | um erro foi relatado pelo provedor de infraestrutura de pagamento. |
| Payment Requests | payment_request_update | payment_request_chargeback | um chargeback foi feito pelo seu usuário. |
Quando um usuário é bloqueado devido a um chargeback, todos os comerciantes recebem o webhook customer_blocked, independentemente de terem ou não esse usuário 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 usuário bloqueado para que você possa verificar se o usuário 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 usuário, mas para outro comerciante, você não receberá outro webhook para esse usuário).
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). 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.
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.