Collect consent with consent links

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

A consent link lets you collect a direct debit authorization without building your own UI. You create the link with one API call and send the URL to your customer. Your customer opens it in their browser, enters their CLABE, reviews and accepts the direct debit authorization, and signs it electronically with a code that Belvo deposits into their account.

When your customer finishes, Belvo has created a payment method and a confirmed consent for them. They are the same resources that you would otherwise create yourself with the Direct Debit API, so you can send payment requests right away.

In this guide, you will:

• Create a consent link for an existing customer, with the payment terms that they must authorize.
• Share the link with your customer and see what they do in the consent link widget.
• Handle the redirect back to your application.
• Listen for webhooks and confirm the result.

Prerequisites

Before you begin, make sure you:

1. Generate your API keys.
2. Set up a webhook to listen to events.
3. Set up IP Whitelisting.
4. Ask your Belvo representative to enable consent links for your account. Consent links use penny validation to deliver the signature code, so penny validation consent must be active for your account.
5. Create a customer for the person you want to debit. The widget shows the customer's name and a masked RFC or CURP from this record, so make sure that the data is correct.

Data flow overview

Create a consent link

To create a consent link, make a POST /consents/links call with the ID of the customer and the payment terms that they must authorize.

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
    }
  }'

Terms object

All terms are optional. The widget only shows the terms that you send, so send every term that applies to the agreement with your customer.

You will receive the following response from our API. Make sure to save the id to check the status of the link later, and send the consentLinkUrl to your customer.

{
  "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"
}

Share the link with your customer

Send the consentLinkUrl to your customer by SMS, email, or WhatsApp, or redirect them to it from your application. The widget works in any mobile or desktop browser, is in Spanish, and doesn't require your customer to log in.

What your customer sees

Your customer goes through the following screens. The widget saves their progress, so if they close the page and open the link again before it expires, they continue on the same screen.

1. Welcome

The welcome screen explains how the process works:

1. Your customer confirms and reviews the direct debit.
2. Belvo deposits $0.01 MXN into their account, with a code.
3. Your customer enters the code to authorize the direct debit.

To continue, your customer must accept Belvo's Terms and Conditions and Privacy Notice.

If you set a callbackUrl, a back arrow lets your customer leave the flow. Belvo redirects them to your callbackUrl with status=cancelled&error=user_cancelled.

2. Confirm personal data and CLABE

The widget shows your customer's full name and masked RFC or CURP from the customer record. Your customer can't edit these values.

Your customer enters their 18-digit CLABE. The widget checks that the CLABE is valid, and Belvo identifies the bank from it. The account must be in your customer's name. Consent links only accept CLABE accounts, not debit cards.

When your customer taps Continuar, Belvo creates the payment method and immediately sends the $0.01 MXN deposit with the code.

If the name or ID is wrong, your customer can tap No soy yo and then Salir sin autorizar. Belvo redirects them to your callbackUrl with status=cancelled&error=customer_data_mismatch. Correct the customer data and create a new link.

3. Review and accept the authorization

The widget shows a summary of the terms that you sent, together with the masked account number, the bank, and your business name as the beneficiary. It also tells your customer that nothing is charged today.

For RECURRING charges, the title reads "Revisa y autoriza tus cargos recurrentes". For SINGLE charges, it reads "Revisa y autoriza tu cargo único". The summary only has a row for each term that you sent.

When your customer taps Continuar, they accept the authorization. Belvo seals the authorization document and stores it as the consent's contract file.

Single charge

This example link has "chargeType": "SINGLE" and only sends chargeAmount and firstChargeDate, so the summary shows the amount, the date of the charge, the account, and the beneficiary.

Contract review

With Revisar contrato de domiciliación, your customer reads the full direct debit contract, filled in with their data and your terms, and can download a PDF copy before they accept.

4. Wait for the deposit

If the deposit hasn't arrived yet, the widget tells your customer to look for a $0.01 MXN deposit in their banking app. The code is in the description of the transaction.

The widget checks for the deposit automatically and moves to the next screen when it arrives. If the deposit already arrived while your customer was reviewing the authorization, the widget skips this screen.

5. Enter the code and authorize

Your customer enters the 6-digit code from the description of the deposit and taps Autorizar. Entering the code is your customer's electronic signature of the authorization.

Your customer has 3 attempts to enter the correct code. If they can't find the deposit, No recibí el depósito explains where to find the code. If your customer entered the wrong CLABE, the deposit never arrives. They can end the flow from the same dialog, and you need to create a new link for them.

6. Authorization confirmed

When the code is correct, the consent is confirmed and the link is completed. The widget shows a summary of the authorized terms.

When your customer taps Cerrar, Belvo redirects them to your callbackUrl with status=completed.

Signed contract

With Contrato de domiciliación, your customer sees the evidence of the electronic signature: the signature date and time (Mexico City time), the signature folio, the device, a masked IP address, and the details of the verification deposit. They can also download the signed contract as a PDF.

Error screens

Link unavailable

The widget shows this screen when the link is expired, revoked, already completed, failed, or invalid. For security reasons, the widget shows the same message in every case. Your customer is asked to request a new link from you.

Authorization failed

The widget shows this screen when Belvo can't complete an action while your customer is in the flow, for example, when the account validation failed after they submitted their CLABE. The screen includes an ID that your customer can share with Belvo support at cobros@belvo.com.

Handle the redirect to your callback URL

If you set a callbackUrl, Belvo redirects your customer to it when they finish or leave the flow. Belvo keeps any query parameters that your URL already has, and adds the following:

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

The redirect never includes the link token or any customer data.

Listen for webhooks and confirm the result

A consent link creates a regular payment method and consent, so you receive the same webhooks as in the Direct Debit Payments via API flow:

• consent_update with consent_confirmed: Your customer entered the correct code and the consent is confirmed. The details.id field is the consentId and details.paymentMethodId is the payment method that the link created.
• payment_method_update with payment_method_registration_successful or payment_method_registration_failed: The result of the account validation. Payment methods created by a consent link have ConsentLink as their reference.

For complete webhook payloads, see our Payment Webhooks (Mexico) documentation.

To check the status of the link at any time, make a GET /consents/links/{id} call. A completed status means that your customer finished the flow.

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'

To identify the payment method that the link created, use the details.paymentMethodId value from the consent_confirmed webhook. Don't look it up by customer_id alone, as your customer can have more than one payment method. To confirm which customer the payment method belongs to, make a GET Get a payment method's details call and compare its customer with the link's customerId. This only confirms the customer: if you created more than one consent link for the same customer, it doesn't tell you which link created the payment method.

Test consent links in Sandbox

In Sandbox, Belvo doesn't send a real $0.01 MXN deposit, so you can't read a code from a bank statement. Instead, you control the result of the flow with the CLABE and the code that your tester enters in the widget. Use the consentLinkUrl that you get from the Sandbox API.

Choose the account validation result

Enter one of the following CLABEs on the personal data and CLABE screen:

Payment methods that you create with these CLABEs use failed or pending as their reference instead of ConsentLink. The magic CLABEs only work in Sandbox. In Production, Belvo treats them as any other CLABE.

Enter the verification code

In Sandbox, the verification code is always 123456. Enter any other code to test the wrong code message. Your tester has 3 attempts to enter the correct code.

Test other link statuses

• Expired: create a link with "expiresIn": 1 and open it after an hour.
• Revoked: make a POST /consents/links/{id}/revoke call, and then open the link.

Consent link reference

Consent link statuses

Only active links can be opened. For any other status, the widget shows the Link unavailable screen.

Consent link steps

When a link is completed, step keeps the last step your customer was on. Always check status first.

Manage consent links

Errors