Qué es y cuándo usarlo
Un link de consentimiento es una URL que creas para un sujeto (una persona o empresa identificada por su documento) para que el titular autorice el acceso de lectura a sus datos bancarios a través de un flujo de conexión seguro. Cuando el titular lo otorga, CBPay deriva hechos positivos (cuentas, saldos, actividad de ingresos y gastos de los últimos 90 días) y los alimenta al historial crediticio del sujeto — el Qscore los refleja en el próximo informe. Úsalo cuando el sujeto tiene poco o ningún historial crediticio y su actividad bancaria es la mejor evidencia de su capacidad real de pago — por ejemplo un arrendatario sin registro en buró, o un proveedor que pide mejores condiciones comerciales.- Tú creas el link (opcionalmente enviado por correo al titular, con el branding de tu organización).
- El titular lo abre, ve tu marca y la finalidad declarada, conecta su banco por el widget seguro y confirma — o rechaza.
- CBPay valida que el documento verificado por el banco calce exactamente con el
doc_iddel sujeto (una cuenta de OTRO documento jamás otorga el consentimiento), deriva los hechos y te notifica por webhook.
Cómo funciona el flujo
El link es una URL de capacidad: el token de 128 bits que lleva ES la autorización para verlo y decidirlo. Funciona sin login, solo muestra tu marca, la finalidad y el documento enmascarado del titular (últimos 4 caracteres), y vence al cumplirse el TTL que elijas (7 días por defecto, 30 máximo).Paso a paso
1
Crea el link de consentimiento
POST /v1/qscore/consents — exige el service flag risk y una cuenta verificada. La idempotency_key es obligatoria: el create envía un correo cuando informas email, y un retry con la misma clave devuelve el consent original con idempotency_hit: true en vez de crear un duplicado.Request
Response 201
country— ISO alpha-2, requerido. Cobertura hoy:CL.doc_id— requerido, validado con el dígito verificador del país (RUT chileno, ej.11111111-1).subject_type—personocompany; se infiere del documento si lo omites.purpose— requerido:credit_evaluation,tenant_screening,hiring,supplier_onboardinguother. La ley de protección de datos exige declararlo.self_accessse rechaza aquí — tu propio informe va porPOST /v1/qscore/my-report.email— opcional; si viene, el titular recibe el link en un correo brandeado de tu organización.expires_in_days— opcional; default 7, máximo 30.
consent_url con el titular (o deja que el correo lo entregue).2
El titular abre el link
La página pública primero carga La vista pública jamás expone el email del titular, el documento completo, IDs internos ni el propio token.
GET /platform/consent/{token} (sin autenticación) para mostrar tu marca, la finalidad declarada y el documento enmascarado:Response 200
3
El titular conecta su banco
Al elegir Autorizar se llama La página monta el widget bancario con esas credenciales; el titular se autentica con su banco y autoriza la conexión. El widget devuelve un
POST /platform/consent/{token}/begin, que abre una sesión segura de conexión bancaria:Response 200
exchange_token a la página.4
El consentimiento queda otorgado
La página envía Antes de sellar el otorgamiento, CBPay verifica dos cosas y rechaza en caso contrario:
POST /platform/consent/{token}/complete con el exchange_token:Request
Response 200
- la conexión bancaria está
active— si no,409 link_inactive; - el documento verificado por el banco calza exactamente con el
doc_iddel sujeto (ambos normalizados) — si no,409 holder_mismatch.
risk_consent_granted.5
Sigue el consentimiento
Response 200
GET /v1/qscore/consents/{id} devuelve un consentimiento puntual (el de otra cuenta responde 404 not_found). Un link pending que pasó su expires_at se marca expired la próxima vez que se lee.6
Revócalo si hace falta
POST /v1/qscore/consents/{id}/revoke cancela un consentimiento (por ejemplo si la operación se cayó). Uno ya otorgado, revocado o expirado responde 409 already_decided. Revocar emite el webhook risk_consent_revoked.Response 200
Estados
Un consentimiento se decide exactamente una vez: todo estado terminal rechaza más transiciones con
409 already_decided.
Errores
Los endpoints públicos (del titular) comparten un throttle por IP con las superficies de verificación: 30 requests por minuto por IP — un429 rate_limited significa bajar el ritmo. Un token inexistente o malformado siempre responde un 404 not_found genérico (anti-enumeración).
Mira el catálogo de errores para la lista completa.
Webhooks
Suscríbete a estos eventos para saber cuándo el titular decide:doc_id viaja completo en el webhook (es data de tu propia cuenta), así puedes reconciliarlo con el sujeto para el que creaste el link.
Cómo alimenta el Qscore
Otorgar un consentimiento gatilla una derivación en background: CBPay lee las cuentas y la actividad del link (últimos 90 días), agrega hechos positivos — cantidad de cuentas, saldos disponible y contable, totales de ingresos y gastos — y los persiste en el historial crediticio del sujeto. Los movimientos crudos jamás se guardan ni se exponen (minimización de datos). Cada informe Qscore generado después re-deriva los consentsgranted del sujeto, así que la data positiva va fresca en cada informe. No necesitas ninguna llamada extra de tu lado.
FAQ
¿El titular necesita una cuenta CBPay?
¿El titular necesita una cuenta CBPay?
No. El link es completamente público y funciona sin login — el token de 128 bits de la URL ES la autorización. El titular solo ve tu marca, la finalidad y su documento enmascarado.
¿Qué pasa si el titular conecta una cuenta de otra persona?
¿Qué pasa si el titular conecta una cuenta de otra persona?
El otorgamiento se rechaza con
409 holder_mismatch: el documento verificado por el banco debe calzar exactamente con el doc_id del sujeto. Una cuenta de OTRO documento jamás otorga el consentimiento — es la prueba de identidad del flujo.¿Puedo revocar un consentimiento ya otorgado?
¿Puedo revocar un consentimiento ya otorgado?
Un consentimiento otorgado es un estado terminal y rechaza transiciones (
409 already_decided). Para dejar de usar la data, deja de generar informes del sujeto; la conexión bancaria misma la administra el titular en su banco.¿Cuánto vive el link?
¿Cuánto vive el link?
7 días por defecto, configurable con
expires_in_days hasta 30. Un link vencido se marca expired y ya no se puede usar — crea uno nuevo.¿El email es obligatorio?
¿El email es obligatorio?
No. Sin
email recibes el consent_url en la respuesta y lo compartes tú (WhatsApp, SMS, tu propio correo). Con email, CBPay envía un correo brandeado en tu nombre. En ambos casos el create exige una idempotency_key.¿Qué países cubre?
¿Qué países cubre?
Cobertura hoy: Chile (
CL). Se suman más corredores a medida que la agregación bancaria está disponible en cada país — crear un link para un país sin cobertura falla al conectar con 502 provider_error.¿Qué datos se derivan exactamente?
¿Qué datos se derivan exactamente?
Solo hechos agregados: cantidad de cuentas, saldos disponible y contable, moneda, instituciones, fecha de primera observación y totales de ingresos/gastos/movimientos a 90 días. Las transacciones individuales jamás se guardan ni se exponen.