Webhooks de Pagamento (México)

Configurando seus webhooks

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.

Eventos de Webhook

{
  "eventType": "payment_request_update", // Tipo de evento do recurso da API
  "eventCode": "payment_request_successful", // Código do evento do webhook
  "datetime": "2022-01-01T12:34:56.789Z", // O timestamp ISO-8601 quando o evento foi enviado.
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // ID do objeto do recurso da API.
    "reference": "your_reference_here", // Descrição opcional do objeto
    "status": "failed", // O status do recurso
    "failedReason": "BANK_CODE", // Se status=failed, um código de falha
    "failedMessage": "A description of the error" // Se status=failed, uma descrição da falha.
  }
}

failedReason and failedMessage fields

Para detalhes sobre os failedReason e failedMessage esperados (incluindo a lista de valores possíveis), consulte nosso guia de Erros de Débito Direto Bancário.

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	Código do Evento	Enviado sempre que...
Métodos de Pagamento	`payment_method_registration_successful`	o registro do método de pagamento de débito direto foi bem-sucedido.
Métodos de Pagamento	`payment_method_registration_failed`	o registro do método de pagamento de débito direto falhou.
Métodos de Pagamento	`payment_method_registration_canceled`	o registro de débito direto foi cancelado (geralmente pelo proprietário).
Solicitações de Pagamento	`payment_request_successful`	o pagamento foi bem-sucedido e recebemos confirmação do provedor de infraestrutura de pagamento.
Solicitações de Pagamento	`payment_request_failed`	um erro é relatado pelo provedor de infraestrutura de pagamento.
Solicitações de Pagamento	`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 Reenvio.

Política de nova tentativa

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á esse padrão até que receba uma resposta bem-sucedida ou atinja o máximo de 10 novas tentativas.

Métodos de Pagamento

payment_method_registration_failed

Você pode receber um payment_method_registration_failed webhook quando o registro do método de pagamento de débito direto falhar para um determinado paymentMethodId.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentMethodId
    "reference": "your_reference_here",
    "status": "error",
    "failedReason": "BANK_CODE",
    "failedMessage": "A description of the error"
  }
}

Fornecemos informações adicionais sobre a falha nas chaves failedReason e failedMessage.

payment_method_registration_canceled

Você pode receber um webhook payment_method_registration_canceled quando o registro do método de pagamento de débito direto foi cancelado (geralmente pelo proprietário) para um determinado paymentMethodId.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_canceled",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentMethodId
    "reference": "your_reference_here",
    "status": "canceled",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_method_registration_successful

Você recebe um webhook payment_method_registration_successful quando o registro do método de pagamento por débito direto é bem-sucedido para um determinado paymentMethodId.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentMethodId
    "reference": "your_reference_here",
    "status": "active",
    "failedReason": null,
    "failedMessage": null
  }
}

Solicitações de Pagamento

payment_request_failed

Você pode receber um payment_request_failed webhook quando um erro é relatado pelo provedor de infraestrutura de pagamento para um determinado paymentRequestId.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentRequestId
    "reference": "your_reference_here",
    "status": "failed",
    "failedReason": "BANK_CODE",
    "failedMessage": "A description of the error"
  }
}

payment_request_successful

Você recebe um payment_request_successful webhook quando o provedor de infraestrutura de pagamento confirma que o pagamento foi bem-sucedido para um determinado paymentRequestId.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentRequestId
    "reference": "your_reference_here",
    "status": "succesful",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_request_canceled

Você recebe um webhook payment_request_canceled quando a solicitação de pagamento foi cancelada pelo cliente.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_canceled",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentRequestId
    "reference": "your_reference_here",
    "status": "canceled",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_request_chargeback

Você recebe um payment_request_chargeback webhook quando o provedor de infraestrutura de pagamento informa que o pagamento resultou em um chargeback pelo cliente.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_chargeback",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentRequestId
    "reference": "your_reference_here",
    "status": "chargeback",
    "failedReason": null,
    "failedMessage": null
  }
}