Recopilar consentimiento con enlaces de consentimiento

Copiar

• Copiar para LLM

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

  Abrir esta página como Markdown
• Abrir en ChatGPT

  Obtener información de ChatGPT
• Abrir en Claude

  Obtener información de Claude
• Conectar a Cursor

  Instalar servidor MCP en Cursor
• Conectar a VS Code

  Instalar servidor MCP en VS Code

Un enlace de consentimiento te permite recopilar una autorización de débito directo sin necesidad de construir tu propia interfaz de usuario. Creas el enlace con una llamada a la API y envías la URL a tu cliente. Tu cliente lo abre en su navegador, ingresa su CLABE, revisa y acepta la autorización de débito directo, y la firma electrónicamente con un código que Belvo deposita en su cuenta.

Cuando tu cliente termina, Belvo ha creado un método de pago y un consentimiento confirmado para ellos. Son los mismos recursos que de otro modo crearías tú mismo con la API de Débito Directo, por lo que puedes enviar solicitudes de pago de inmediato.

En esta guía, tú:

• Crearás un enlace de consentimiento para un cliente existente, con los términos de pago que deben autorizar.
• Compartirás el enlace con tu cliente y verás qué hacen en el widget de enlace de consentimiento.
• Manejarás la redirección de vuelta a tu aplicación.
• Escucharás los webhooks y confirmarás el resultado.

Requisitos previos

Antes de comenzar, asegúrate de:

1. Generar tus claves API.
2. Configurar un webhook para escuchar eventos.
3. Configurar la lista blanca de IPs.
4. Pedir a tu representante de Belvo que habilite los enlaces de consentimiento para tu cuenta. Los enlaces de consentimiento utilizan la validación de centavos para entregar el código de firma, por lo que el consentimiento de validación de centavos debe estar activo para tu cuenta.
5. Crear un cliente para la persona a la que deseas debitar. El widget muestra el nombre del cliente y un RFC o CURP enmascarado de este registro, así que asegúrate de que los datos sean correctos.

Descripción general del flujo de datos

Crear un enlace de consentimiento

Para crear un enlace de consentimiento, realiza una llamada POST /consents/links con el ID del cliente y los términos de pago que deben 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 términos

Todos los términos son opcionales. El widget solo muestra los términos que envías, así que envía cada término que aplique al acuerdo con tu cliente.

Recibirás la siguiente respuesta de nuestra API. Asegúrate de guardar el id para verificar el estado del enlace más tarde, y envía el consentLinkUrl a tu 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"
}

Comparte el enlace con tu cliente

Envía el consentLinkUrl a tu cliente por SMS, correo electrónico o WhatsApp, o redirígelo desde tu aplicación. El widget funciona en cualquier navegador móvil o de escritorio, está en español y no requiere que tu cliente inicie sesión.

Lo que ve tu cliente

Tu cliente pasa por las siguientes pantallas. El widget guarda su progreso, por lo que si cierra la página y vuelve a abrir el enlace antes de que expire, continuará en la misma pantalla.

1. Bienvenido

La pantalla de bienvenida explica cómo funciona el proceso:

1. Tu cliente confirma y revisa el débito directo.
2. Belvo deposita $0.01 MXN en su cuenta, con un código.
3. Tu cliente ingresa el código para autorizar el débito directo.

Para continuar, tu cliente debe aceptar los Términos y Condiciones y el Aviso de Privacidad de Belvo.

Si configuras un callbackUrl, una flecha de retroceso permite a tu cliente salir del flujo. Belvo los redirige a tu callbackUrl con status=cancelled&error=user_cancelled.

2. Confirmar datos personales y CLABE

El widget muestra el nombre completo de tu cliente y el RFC o CURP enmascarado del registro del cliente. Tu cliente no puede editar estos valores.

Tu cliente ingresa su CLABE de 18 dígitos. El widget verifica que la CLABE sea válida, y Belvo identifica el banco a partir de ella. La cuenta debe estar a nombre de tu cliente. Los enlaces de consentimiento solo aceptan cuentas CLABE, no tarjetas de débito.

Cuando tu cliente toca Continuar, Belvo crea el método de pago y envía inmediatamente el depósito de $0.01 MXN con el código.

Si el nombre o ID es incorrecto, tu cliente puede tocar No soy yo y luego Salir sin autorizar. Belvo los redirige a tu callbackUrl con status=cancelled&error=customer_data_mismatch. Corrige los datos del cliente y crea un nuevo enlace.

3. Revisa y acepta la autorización

El widget muestra un resumen de los términos que enviaste, junto con el número de cuenta enmascarado, el banco y el nombre de tu empresa como beneficiario. También informa a tu cliente que hoy no se cobra nada.

Para cargos RECURRING, el título dice "Revisa y autoriza tus cargos recurrentes". Para cargos SINGLE, dice "Revisa y autoriza tu cargo único". El resumen solo tiene una fila por cada término que enviaste.

Cuando tu cliente toca Continuar, acepta la autorización. Belvo sella el documento de autorización y lo almacena como el archivo contract del consentimiento.

Cargo único

Este enlace de ejemplo tiene "chargeType": "SINGLE" y solo envía chargeAmount y firstChargeDate, por lo que el resumen muestra el monto, la fecha del cargo, la cuenta y el beneficiario.

Revisión del contrato

Con Revisar contrato de domiciliación, tu cliente lee el contrato completo de domiciliación, rellenado con sus datos y tus términos, y puede descargar una copia en PDF antes de aceptar.

4. Espera el depósito

Si el depósito aún no ha llegado, el widget le indica a tu cliente que busque un depósito de $0.01 MXN en su aplicación bancaria. El código está en la descripción de la transacción.

El widget verifica automáticamente el depósito y pasa a la siguiente pantalla cuando llega. Si el depósito ya llegó mientras tu cliente revisaba la autorización, el widget omite esta pantalla.

5. Ingresar el código y autorizar

Tu cliente ingresa el código de 6 dígitos de la descripción del depósito y toca Autorizar. Ingresar el código es la firma electrónica de autorización de tu cliente.

Tu cliente tiene 3 intentos para ingresar el código correcto. Si no pueden encontrar el depósito, No recibí el depósito explica dónde encontrar el código. Si tu cliente ingresó la CLABE incorrecta, el depósito nunca llega. Pueden finalizar el flujo desde el mismo diálogo, y necesitas crear un nuevo enlace para ellos.

6. Autorización confirmada

Cuando el código es correcto, el consentimiento se confirma y el enlace se marca como completed. El widget muestra un resumen de los términos autorizados.

Cuando tu cliente toca Cerrar, Belvo los redirige a tu callbackUrl con status=completed.

Contrato firmado

Con Contrato de domiciliación, tu cliente ve la evidencia de la firma electrónica: la fecha y hora de la firma (hora de Ciudad de México), el folio de la firma, el dispositivo, una dirección IP enmascarada y los detalles del depósito de verificación. También pueden descargar el contrato firmado como un PDF.

Pantallas de error

Enlace no disponible

El widget muestra esta pantalla cuando el enlace ha expirado, ha sido revocado, ya se ha completado, ha fallado o es inválido. Por razones de seguridad, el widget muestra el mismo mensaje en cada caso. Se le pide a tu cliente que solicite un nuevo enlace de tu parte.

Autorización fallida

El widget muestra esta pantalla cuando Belvo no puede completar una acción mientras tu cliente está en el flujo, por ejemplo, cuando la validación de la cuenta falla después de que han enviado su CLABE. La pantalla incluye un ID que tu cliente puede compartir con el soporte de Belvo en cobros@belvo.com.

Manejar la redirección a tu URL de callback

Si configuras un callbackUrl, Belvo redirige a tu cliente a esta cuando terminan o abandonan el flujo. Belvo mantiene cualquier parámetro de consulta que tu URL ya tenga y añade los siguientes:

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

La redirección nunca incluye el token de enlace ni ningún dato del cliente.

Escuchar webhooks y confirmar el resultado

Un enlace de consentimiento crea un método de pago regular y un consentimiento, por lo que recibes los mismos webhooks que en el flujo de Pagos por Débito Directo vía API:

• consent_update con consent_confirmed: Tu cliente ingresó el código correcto y el consentimiento está confirmado. El campo details.id es el consentId y details.paymentMethodId es el método de pago que el enlace creó.
• payment_method_update con payment_method_registration_successful o payment_method_registration_failed: El resultado de la validación de la cuenta. Los métodos de pago creados por un enlace de consentimiento tienen ConsentLink como su reference.

Para ver los payloads completos de los webhooks, consulta nuestra documentación de Webhooks de Pagos (México).

Para verificar el estado del enlace en cualquier momento, realiza una llamada GET /consents/links/{id}. Un estado completed significa que tu cliente terminó el flujo.

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 el método de pago que el enlace creó, utiliza el valor details.paymentMethodId del webhook consent_confirmed. No lo busques solo por customer_id, ya que tu cliente puede tener más de un método de pago. Para confirmar a qué cliente pertenece el método de pago, realiza una llamada GET para obtener los detalles de un método de pago y compara su customer con el customerId del enlace. Esto solo confirma el cliente: si creaste más de un enlace de consentimiento para el mismo cliente, no te dice qué enlace creó el método de pago.

Probar enlaces de consentimiento en Sandbox

En Sandbox, Belvo no envía un depósito real de $0.01 MXN, por lo que no puedes leer un código de un estado de cuenta bancario. En su lugar, controlas el resultado del flujo con la CLABE y el código que tu tester ingresa en el widget. Usa el consentLinkUrl que obtienes de la API de Sandbox.

Elige el resultado de validación de cuenta

Ingresa una de las siguientes CLABEs en la pantalla de datos personales y CLABE:

Los métodos de pago que creas con estas CLABEs usan failed o pending como su reference en lugar de ConsentLink. Las CLABEs mágicas solo funcionan en Sandbox. En Producción, Belvo las trata como cualquier otra CLABE.

Ingresa el código de verificación

En Sandbox, el código de verificación siempre es 123456. Ingresa cualquier otro código para probar el mensaje de código incorrecto. Tu evaluador tiene 3 intentos para ingresar el código correcto.

Probar otros estados de enlaces

• Expirado: crea un enlace con "expiresIn": 1 y ábrelo después de una hora.
• Revocado: realiza una llamada POST /consents/links/{id}/revoke, y luego abre el enlace.

Referencia de enlace de consentimiento

Estados de los enlaces de consentimiento

Solo los enlaces active pueden ser abiertos. Para cualquier otro estado, el widget muestra la pantalla de Enlace no disponible.

Pasos del enlace de consentimiento

Cuando un enlace está completed, step mantiene el último paso en el que estaba tu cliente. Siempre verifica status primero.

Administrar enlaces de consentimiento

Errores