Coletar consentimento com links de consentimento

Copiar

• Copiar para LLM

  Copiar página como Markdown para LLMs
• Ver como Markdown

  Abrir esta página como Markdown
• Abrir no ChatGPT

  Obter insights do ChatGPT
• Abrir no Claude

  Obter insights do Claude
• Conectar ao Cursor

  Instalar servidor MCP no Cursor
• Conectar ao VS Code

  Instalar servidor MCP no VS Code

Um link de consentimento permite que você colete uma autorização de débito direto sem precisar construir sua própria interface de usuário. Você cria o link com uma chamada de API e envia a URL para o seu cliente. Seu cliente a abre no navegador, insere sua CLABE, revisa e aceita a autorização de débito direto, e a assina eletronicamente com um código que a Belvo deposita em sua conta.

Quando seu cliente termina, a Belvo criou um método de pagamento e um consentimento confirmado para ele. São os mesmos recursos que você criaria por conta própria com a API de Débito Direto, permitindo que você envie solicitações de pagamento imediatamente.

Neste guia, você irá:

• Criar um link de consentimento para um cliente existente, com os termos de pagamento que ele deve autorizar.
• Compartilhar o link com seu cliente e ver o que ele faz no widget de link de consentimento.
• Lidar com o redirecionamento de volta para sua aplicação.
• Ouvir os webhooks e confirmar o resultado.

Pré-requisitos

Antes de começar, certifique-se de:

1. Gerar suas chaves de API.
2. Configurar um webhook para escutar eventos.
3. Configurar a Lista Branca de IPs.
4. Solicitar ao seu representante da Belvo para habilitar links de consentimento para sua conta. Os links de consentimento usam validação de centavos para entregar o código de assinatura, portanto, o consentimento de validação de centavos deve estar ativo para sua conta.
5. Criar um cliente para a pessoa que você deseja debitar. O widget mostra o nome do cliente e um RFC ou CURP mascarado deste registro, então certifique-se de que os dados estão corretos.

Visão geral do fluxo de dados

Criar um link de consentimento

Para criar um link de consentimento, faça uma chamada POST /consents/links com o ID do cliente e os termos de pagamento que ele deve autorizar.

curl -i -X POST \
  'https://api.sandbox.directdebit.belvo.com/consents/links' \
  -H 'Content-Type: application/json' \
  -H 'api-key-id: YOUR_API_KEY_ID' \
  -H 'api-key-secret: YOUR_API_KEY_SECRET' \
  -d '{
    "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
    "expiresIn": 72,
    "callbackUrl": "https://www.your-app.com/direct-debit/return",
    "terms": {
      "chargeType": "RECURRING",
      "chargeAmount": 420.00,
      "paymentFrequency": "MONTHLY",
      "serviceOrCreditDescription": "Préstamo personal",
      "termDescription": "12 meses",
      "interestRate": "1,0% mensual",
      "numberOfCharges": 12,
      "firstChargeDate": "2026-11-10",
      "isPayrollLinked": false
    }
  }'

Objeto de Termos

Todos os termos são opcionais. O widget só mostra os termos que você envia, então envie todos os termos que se aplicam ao acordo com seu cliente.

Você receberá a seguinte resposta da nossa API. Certifique-se de salvar o id para verificar o status do link mais tarde, e enviar o consentLinkUrl para seu cliente.

{
  "id": "b8e1c2f4-5a6d-4e7f-8a9b-0c1d2e3f4a5b", 
  "consentLinkUrl": "https://portal.sandbox.directdebit.belvo.com/consent.html?token=aB3dE6fG9hJ2kL5mN8pQ1rS4", 
  "status": "active",
  "step": "bank_account",
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "terms": {
    "chargeType": "RECURRING",
    "chargeAmount": 420,
    "paymentFrequency": "MONTHLY",
    "serviceOrCreditDescription": "Préstamo personal",
    "termDescription": "12 meses",
    "interestRate": "1,0% mensual",
    "numberOfCharges": 12,
    "firstChargeDate": "2026-11-10",
    "isPayrollLinked": false
  },
  "expiresAt": "2026-10-03T15:00:00.000Z",
  "callbackUrl": "https://www.your-app.com/direct-debit/return"
}

Compartilhe o link com seu cliente

Envie o consentLinkUrl para seu cliente por SMS, email ou WhatsApp, ou redirecione-o a partir do seu aplicativo. O widget funciona em qualquer navegador móvel ou desktop, está em espanhol e não requer que seu cliente faça login.

O que seu cliente vê

Seu cliente passa pelas seguintes telas. O widget salva o progresso deles, então, se fecharem a página e abrirem o link novamente antes que ele expire, continuarão na mesma tela.

1. Bem-vindo

A tela de boas-vindas explica como o processo funciona:

1. Seu cliente confirma e revisa o débito direto.
2. A Belvo deposita $0,01 MXN na conta deles, com um código.
3. Seu cliente insere o código para autorizar o débito direto.

Para continuar, seu cliente deve aceitar os Termos e Condições e o Aviso de Privacidade da Belvo.

Se você definir um callbackUrl, uma seta para trás permite que seu cliente saia do fluxo. A Belvo os redireciona para o seu callbackUrl com status=cancelled&error=user_cancelled.

2. Confirme os dados pessoais e CLABE

O widget mostra o nome completo do seu cliente e o RFC ou CURP mascarado do registro do cliente. Seu cliente não pode editar esses valores.

Seu cliente insere sua CLABE de 18 dígitos. O widget verifica se a CLABE é válida, e a Belvo identifica o banco a partir dela. A conta deve estar no nome do seu cliente. Links de consentimento aceitam apenas contas CLABE, não cartões de débito.

Quando seu cliente toca em Continuar, a Belvo cria o método de pagamento e imediatamente envia o depósito de $0,01 MXN com o código.

Se o nome ou ID estiver errado, seu cliente pode tocar em No soy yo e depois em Salir sin autorizar. A Belvo os redireciona para o seu callbackUrl com status=cancelled&error=customer_data_mismatch. Corrija os dados do cliente e crie um novo link.

3. Revise e aceite a autorização

O widget mostra um resumo dos termos que você enviou, junto com o número da conta mascarado, o banco e o nome da sua empresa como beneficiário. Ele também informa ao seu cliente que nada será cobrado hoje.

Para cobranças RECURRING, o título diz "Revisa y autoriza tus cargos recurrentes". Para cobranças SINGLE, diz "Revisa y autoriza tu cargo único". O resumo possui apenas uma linha para cada termo que você enviou.

Quando seu cliente toca em Continuar, ele aceita a autorização. A Belvo sela o documento de autorização e o armazena como o arquivo contract do consentimento.

Cobrança única

Este link de exemplo tem "chargeType": "SINGLE" e envia apenas chargeAmount e firstChargeDate, então o resumo mostra o valor, a data da cobrança, a conta e o beneficiário.

Revisão do contrato

Com Revisar contrato de domiciliación, seu cliente lê o contrato completo de débito direto, preenchido com seus dados e seus termos, e pode baixar uma cópia em PDF antes de aceitar.

4. Aguarde o depósito

Se o depósito ainda não chegou, o widget informa ao seu cliente para procurar um depósito de $0,01 MXN no aplicativo bancário. O código está na descrição da transação.

O widget verifica o depósito automaticamente e avança para a próxima tela quando ele chega. Se o depósito já tiver chegado enquanto seu cliente estava revisando a autorização, o widget pula esta tela.

5. Insira o código e autorize

Seu cliente insere o código de 6 dígitos da descrição do depósito e toca em Autorizar. Inserir o código é a assinatura eletrônica do seu cliente para a autorização.

Seu cliente tem 3 tentativas para inserir o código correto. Se não conseguir encontrar o depósito, No recibí el depósito explica onde encontrar o código. Se seu cliente inseriu a CLABE errada, o depósito nunca chega. Eles podem encerrar o fluxo a partir do mesmo diálogo, e você precisará criar um novo link para eles.

6. Autorização confirmada

Quando o código está correto, o consentimento é confirmado e o link é completed. O widget mostra um resumo dos termos autorizados.

Quando seu cliente toca em Cerrar, a Belvo os redireciona para o seu callbackUrl com status=completed.

Contrato assinado

Com Contrato de domiciliación, seu cliente vê a evidência da assinatura eletrônica: a data e hora da assinatura (horário da Cidade do México), o folio da assinatura, o dispositivo, um endereço IP mascarado e os detalhes do depósito de verificação. Eles também podem baixar o contrato assinado como um PDF.

Telas de erro

Link indisponível

O widget exibe esta tela quando o link está expirado, revogado, já concluído, falhou ou é inválido. Por razões de segurança, o widget mostra a mesma mensagem em todos os casos. Seu cliente é solicitado a pedir um novo link para você.

Falha na autorização

O widget exibe esta tela quando a Belvo não consegue completar uma ação enquanto seu cliente está no fluxo, por exemplo, quando a validação da conta falha após a submissão do CLABE. A tela inclui um ID que seu cliente pode compartilhar com o suporte da Belvo em cobros@belvo.com.

Lidar com o redirecionamento para sua URL de callback

Se você definir um callbackUrl, a Belvo redireciona seu cliente para ela quando ele termina ou sai do fluxo. A Belvo mantém quaisquer parâmetros de consulta que sua URL já tenha e adiciona os seguintes:

https://www.your-app.com/direct-debit/return?status=completed

O redirecionamento nunca inclui o token de link ou quaisquer dados do cliente.

Ouça os webhooks e confirme o resultado

Um link de consentimento cria um método de pagamento regular e consentimento, então você recebe os mesmos webhooks que no fluxo de Pagamentos por Débito Direto via API:

• consent_update com consent_confirmed: Seu cliente inseriu o código correto e o consentimento está confirmado. O campo details.id é o consentId e details.paymentMethodId é o método de pagamento que o link criou.
• payment_method_update com payment_method_registration_successful ou payment_method_registration_failed: O resultado da validação da conta. Métodos de pagamento criados por um link de consentimento têm ConsentLink como sua reference.

Para payloads completos de webhooks, veja nossa documentação de Webhooks de Pagamento (México).

Para verificar o status do link a qualquer momento, faça uma chamada GET /consents/links/{id}. Um status completed significa que seu cliente finalizou o fluxo.

curl -i -X GET \
  'https://api.sandbox.directdebit.belvo.com/consents/links/{id}' \
  -H 'api-key-id: YOUR_API_KEY_ID' \
  -H 'api-key-secret: YOUR_API_KEY_SECRET'

Para identificar o método de pagamento que o link criou, use o valor details.paymentMethodId do webhook consent_confirmed. Não procure apenas pelo customer_id, pois seu cliente pode ter mais de um método de pagamento. Para confirmar a qual cliente o método de pagamento pertence, faça uma chamada GET para obter os detalhes de um método de pagamento e compare seu customer com o customerId do link. Isso apenas confirma o cliente: se você criou mais de um link de consentimento para o mesmo cliente, isso não indica qual link criou o método de pagamento.

Testar links de consentimento no Sandbox

No Sandbox, a Belvo não envia um depósito real de $0,01 MXN, então você não pode ler um código de um extrato bancário. Em vez disso, você controla o resultado do fluxo com a CLABE e o código que seu testador insere no widget. Use o consentLinkUrl que você obtém da API do Sandbox.

Escolha o resultado da validação da conta

Insira uma das seguintes CLABEs na tela de dados pessoais e CLABE:

Os métodos de pagamento que você cria com essas CLABEs usam failed ou pending como sua reference em vez de ConsentLink. As CLABEs mágicas funcionam apenas no Sandbox. Em Produção, a Belvo as trata como qualquer outra CLABE.

Insira o código de verificação

No Sandbox, o código de verificação é sempre 123456. Insira qualquer outro código para testar a mensagem de código incorreto. Seu testador tem 3 tentativas para inserir o código correto.

Testar outros status de link

• Expirado: crie um link com "expiresIn": 1 e abra-o após uma hora.
• Revogado: faça uma chamada POST /consents/links/{id}/revoke e, em seguida, abra o link.

Referência de link de consentimento

Status dos links de consentimento

Apenas links active podem ser abertos. Para qualquer outro status, o widget mostra a tela Link indisponível.

Etapas do link de consentimento

Quando um link está completed, step mantém a última etapa em que seu cliente estava. Sempre verifique status primeiro.

Gerenciar links de consentimento

Erros