# Coletar consentimento com links de consentimento 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. Links de consentimento substituem duas etapas da API Um link de consentimento substitui as etapas **Criar um método de pagamento** e **Criar um consentimento** do guia Pagamentos por Débito Direto via API. Você ainda cria o cliente com a API e ainda cria solicitações de pagamento com a API. ## 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 ```mermaid sequenceDiagram participant App as Your application participant Customer as Customer participant Widget as Consent link widget participant Belvo as Belvo participant Bank as Customer's bank Note over App,Bank: 1. Create the consent link App->>Belvo: POST /consents/links Belvo-->>App: 201 - Created + id + consentLinkUrl Note over App,Bank: 2. Share the link App->>Customer: Send consentLinkUrl (SMS, email, WhatsApp, or redirect) Customer->>Widget: Open consentLinkUrl Note over App,Bank: 3. Customer completes the widget Widget->>Belvo: Submit CLABE Belvo->>Bank: Send a $0.01 MXN deposit with a code Widget->>Belvo: Accept the authorization Customer->>Widget: Enter the code from the deposit Widget->>Belvo: Verify the code (electronic signature) Belvo-->>Widget: Link completed Note over App,Bank: 4. Confirm the result Belvo->>App: WEBHOOK consent_confirmed (consentId, paymentMethodId) Widget->>App: Redirect to callbackUrl?status=completed App->>Belvo: GET /consents/links/{id} Belvo-->>App: 200 + status completed ``` ## 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. Sandbox ```curl Create a Consent Link Request (Sandbox) 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 } }' ``` Produção ```curl Create a Consent Link Request (Production) curl -i -X POST \ 'https://api.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 } }' ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `customerId` | string (UUID) | true | O `customerId` do cliente que deve autorizar o débito direto. O cliente deve pertencer à sua conta. | | `terms` | objeto | false | Os termos de pagamento que seu cliente revisa e autoriza no widget. Para detalhes, veja a tabela Objeto Terms abaixo. | | `expiresIn` | inteiro | false | O número de horas até que o link expire. Mínimo `1`, máximo `720` (30 dias). Padrão: `72`. | | `callbackUrl` | string | false | A URL para a qual o widget envia seu cliente de volta quando ele termina ou sai do fluxo. A Belvo adiciona o resultado como parâmetros de consulta. A URL deve usar `https`, não deve conter credenciais e pode ter no máximo 2048 caracteres. Você só pode defini-la quando criar o link. Para detalhes, veja Como lidar com o redirecionamento para sua URL de callback. | ### 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. Envie valores brutos, não texto formatado Envie `chargeAmount` como um número JSON (por exemplo, `420.00`), não como uma string. A Belvo rejeita valores pré-formatados como `"$420.00 MXN"` ou `"420.00"`. O valor está sempre em pesos mexicanos (MXN), e a Belvo o formata para seu cliente. Envie `chargeType` e `paymentFrequency` em maiúsculas (por exemplo, `RECURRING` e `MONTHLY`). A Belvo rejeita valores em minúsculas. | Parâmetro | Tipo | Descrição | | --- | --- | --- | | `chargeType` | string (enum) | O tipo de cobrança que seu cliente autoriza. Pode ser um dos seguintes: - `RECURRING`: Cobranças que se repetem em um cronograma, como parcelas de empréstimos ou assinaturas. - `SINGLE`: Uma única cobrança. Para `SINGLE`, o widget rotula o valor e a data como uma cobrança única ("Monto de cargo (cargo único)" e "Fecha del cargo"). | | `chargeAmount` | number | O valor de cada cobrança, em MXN. Deve ser pelo menos `1`. A Belvo arredonda para duas casas decimais. Por exemplo, `1234.5` é mostrado para seu cliente como "$1,234.50 MXN". | | `paymentFrequency` | string (enum) | Com que frequência você cobra seu cliente. Pode ser um dos seguintes: `MONTHLY` (mostrado como "Mensual"), `BIWEEKLY` (mostrado como "Quincenal"), ou `WEEKLY` (mostrado como "Semanal"). | | `serviceOrCreditDescription` | string | Uma descrição do serviço ou crédito, em espanhol. Por exemplo, `Préstamo personal`. | | `termDescription` | string | Uma descrição do prazo do acordo, em espanhol. Por exemplo, `12 meses`. | | `interestRate` | string | A taxa de juros, formatada como você deseja que seu cliente a leia. Por exemplo, `1,0% mensual`. | | `numberOfCharges` | integer | O número total de cobranças. Deve ser pelo menos `1`. | | `firstChargeDate` | string | A data da primeira cobrança, no formato `YYYY-MM-DD`. Por exemplo, `2026-11-10`. | | `isPayrollLinked` | boolean | Indica se o crédito está vinculado à folha de pagamento do seu cliente. | Permita que seu cliente revise o contrato completo Seu cliente só pode abrir o contrato completo de débito direto (**Revisar contrato de domiciliación**) quando o link tiver um `chargeAmount`, e também um `paymentFrequency` para cobranças `RECURRING`. Certifique-se de enviar esses termos. 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. ```json Create a Consent Link Response Body { "id": "b8e1c2f4-5a6d-4e7f-8a9b-0c1d2e3f4a5b", // [!code highlight] "consentLinkUrl": "https://portal.sandbox.directdebit.belvo.com/consent.html?token=aB3dE6fG9hJ2kL5mN8pQ1rS4", // [!code highlight] "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" } ``` | Parâmetro | Tipo | Descrição | | --- | --- | --- | | `id` | string (UUID) | O ID da Belvo do link de consentimento. | | `consentLinkUrl` | string | A URL que você envia para seu cliente. | | `status` | string | O status do link. Para os valores possíveis, veja Status dos links de consentimento. | | `step` | string | A tela em que seu cliente está enquanto o link está `active`. Para os valores possíveis, veja Etapas dos links de consentimento. | | `customerId` | string (UUID) | O `customerId` ao qual o link pertence. | | `terms` | object | Os termos, exatamente como você os enviou. | | `expiresAt` | string | O timestamp ISO-8601 quando o link expira. | | `completedAt` | string | O timestamp ISO-8601 quando seu cliente completou o link. Presente apenas para links `completed`. | | `callbackUrl` | string | A URL de callback, se você definiu uma. | ## 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. Trate o link como um segredo Qualquer pessoa com o `consentLinkUrl` pode abrir o widget para seu cliente. Envie-o apenas para seu cliente e não o registre ou adicione a ferramentas de análise. Se você achar que um link foi compartilhado com a pessoa errada, revogue-o e crie um novo. Veja Gerenciar links de consentimento. ## 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`. Tela de boas-vindas do link de consentimento ### 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. Tela de dados pessoais e CLABE do link de consentimento ### 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. Resumo da autorização para cobranças recorrentes **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. Resumo da autorização para uma cobrança única **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. Revisão do contrato de débito direto ### 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. Aguardando o depósito de verificação ### 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. Tela de código de verificação ### 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`. Tela de autorização confirmada **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. Contrato assinado com detalhes da assinatura eletrônica ### 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ê. Tela de link indisponível **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. Tela de falha na autorização ## 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: | `status` | `error` | Quando | | --- | --- | --- | | `completed` | Não presente | Seu cliente autorizou o débito direto e tocou em **Cerrar** na tela de confirmação. | | `cancelled` | `user_cancelled` | Seu cliente saiu da tela de boas-vindas. | | `cancelled` | `customer_data_mismatch` | Seu cliente informou que o nome ou ID no widget não é dele. | ```text Exemplo de redirecionamento https://www.your-app.com/direct-debit/return?status=completed ``` O redirecionamento nunca inclui o token de link ou quaisquer dados do cliente. Não confie apenas no redirecionamento Use o redirecionamento para atualizar sua interface de usuário, mas sempre confirme o resultado com a API ou webhooks antes de criar solicitações de pagamento. Qualquer pessoa pode abrir sua URL de callback com quaisquer parâmetros, e seu cliente pode fechar a página sem ser redirecionado. Além disso, ignore quaisquer valores de parâmetros que você não reconheça, pois podemos adicionar novos. ## 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. Sandbox ```curl Get a Consent Link Request (Sandbox) 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' ``` Produção ```curl Get a Consent Link Request (Production) curl -i -X GET \ 'https://api.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. Feito! Seu cliente autorizou o débito direto, e você tem um método de pagamento com consentimento confirmado. Agora você pode criar solicitações de pagamento para este cliente. ## 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: | CLABE | Resultado | | --- | --- | | `012180000000000015` | A validação da conta falha. O método de pagamento é `failed`, o status do link muda para `failed`, e o widget mostra uma tela de erro. Para mais detalhes, veja Telas de erro. | | `012180000000000028` | O depósito nunca chega. O método de pagamento permanece em `pending_validation`, e o link fica na etapa `awaiting_deposit` até expirar. Use-o para testar a tela de espera. | | Qualquer outra CLABE válida | O depósito chega imediatamente. O link avança para a etapa de `verification` assim que seu testador aceita a autorização, e o widget pula a tela de espera. | 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 | Status | Descrição | | --- | --- | | `active` | O link pode ser usado. Verifique `step` para ver em qual tela seu cliente está. | | `completed` | Seu cliente autorizou o débito direto. O consentimento está confirmado. | | `expired` | O link atingiu sua data de `expiresAt` antes de seu cliente completá-lo. | | `revoked` | Você revogou o link. | | `failed` | A validação da conta falhou, por exemplo, porque o titular da conta não corresponde ao cliente. Crie um novo link para que seu cliente possa tentar novamente com uma conta diferente. | Apenas links `active` podem ser abertos. Para qualquer outro status, o widget mostra a tela **Link indisponível**. ### Etapas do link de consentimento | Etapa | Descrição | | --- | --- | | `bank_account` | Seu cliente ainda não enviou sua CLABE. | | `authorization` | Seu cliente enviou sua CLABE e está revisando a autorização. | | `awaiting_deposit` | Seu cliente aceitou a autorização e está aguardando o depósito de $0,01 MXN. | | `verification` | O depósito chegou e seu cliente deve inserir o código. | Quando um link está `completed`, `step` mantém a última etapa em que seu cliente estava. Sempre verifique `status` primeiro. ### Gerenciar links de consentimento | Requisição | Descrição | | --- | --- | | `GET /consents/links` | Lista seus links de consentimento, paginados. Suporta os parâmetros de consulta `page` e `limit`. | | `GET /consents/links/{id}` | Obtém os detalhes de um link de consentimento. | | `POST /consents/links/{id}/revoke` | Revoga um link de consentimento. O link não poderá mais ser aberto. Revogar um link não altera um método de pagamento ou consentimento que o link já criou. | ### Erros | Status HTTP | Descrição | | --- | --- | | `400` | O corpo da solicitação é inválido. Por exemplo, `chargeAmount` é uma string ou menor que `1`, `chargeType` está em minúsculas, ou `callbackUrl` não usa `https`. | | `404` | O cliente ou link de consentimento não existe ou não pertence à sua conta. |