Conectar cuentas
Widget de conexión
El widget es la ventana donde tu usuario elige su banco y autoriza la conexión. Se abre sobre tu aplicación, se encarga del formulario, del segundo factor y de los errores del banco, y te devuelve el link cuando todo terminó.
Flujo
- Consentimiento. «Tu empresa se conectará con tu banco usando Banky», con lo que significa: conexión cifrada, solo lectura y enlaces a Términos y Privacidad. El nombre que aparece es el
client_namedel link token o, si no lo enviaste, el de tu organización. - Banco. Lista de instituciones con su estado; las que están próximamente aparecen deshabilitadas.
- Credenciales. El formulario propio de cada banco (por ejemplo RUT y clave, o RUT de empresa, RUT personal y clave). Se valida en el navegador antes de enviarlo.
- Conexión. El banco puede tardar entre 10 y 40 segundos en responder. Si pide un segundo factor (Multipass, código de prueba…), el widget lo solicita.
- Listo. Se crea el link y se leen cuentas y movimientos. Al cerrar la pantalla de éxito, el widget llama a
onSuccess.
Instalación
Agrega el script en las páginas donde vas a abrir el widget. Expone el objeto global Banky.
index.html
<script src="https://banky.cl/connect.js"></script>Luego, cuando la persona pida conectar su banco, crea un link token en tu servidor (ver Link tokens) y abre el widget:
app.js
const { link_token } = await fetch("/api/link-token", { method: "POST" }).then((r) => r.json());
const widget = Banky.open({
token: link_token,
onSuccess(link) {
// La cuenta quedó conectada. Envía link.id a tu servidor y guárdalo.
guardarConexion(link.id);
},
onExit(error) {
// La persona cerró el widget. error es null si salió sin un error.
if (error) mostrarAviso(error.message);
},
});
// Opcional: cerrarlo desde tu código (llama a onExit con null).
// widget.close();En React, carga el script una vez (por ejemplo en el layout) y ábrelo desde un manejador de evento:
BotonConectar.jsx
import { useCallback } from "react";
export function BotonConectar({ onConectado }) {
const abrir = useCallback(async () => {
const { link_token } = await fetch("/api/link-token", { method: "POST" }).then((r) => r.json());
window.Banky.open({
token: link_token,
onSuccess: (link) => onConectado(link),
onExit: () => {},
});
}, [onConectado]);
return <button onClick={abrir}>Conectar mi banco</button>;
}Opciones
Banky.open(opciones) recibe:
tokenstringobligatorio- El
link_tokencreado por tu servidor. Es de un solo uso y vence a los 30 minutos: crea uno nuevo cada vez que abras el widget. onSuccessfunction(link)- Se llama con el objeto link cuando la persona cierra la pantalla de éxito. La conexión ya existe desde que se mostró esa pantalla.
onExitfunction(error | null)- Se llama cuando el widget se cierra sin conectar. Recibe
nullsi la persona lo cerró, o un objeto{ code, message }si hubo un error que no se pudo resolver dentro del widget.
Devuelve un objeto con el método close(), para cerrar el widget desde tu código. Si el token no tiene el formato de un link token, open lanza un error. Solo puede haber un widget abierto a la vez: abrir otro cierra el anterior. La persona también puede cerrarlo con la tecla Escape; en ambos casos se llama a onExit(null).
En pantallas angostas el widget ocupa toda la pantalla; en escritorio se muestra como un modal de 420 px de ancho.
Eventos
onSuccess recibe el link recién creado. Su id es lo que necesitas guardar:
link
{
"id": "link_9f2c41ab7e05d318",
"object": "link",
"institution": {
"id": "sandbox",
"name": "Banco de Prueba"
},
"holder_type": "business",
"holder_name": "Panadería La Espiga SpA",
"holder_id": "76123874-4",
"status": "active",
"status_message": null,
"mode": "test",
"allow_mcp": true,
"last_refreshed_at": "2026-11-18T14:02:11.482Z",
"next_refresh_at": "2026-11-19T14:02:11.482Z",
"created_at": "2026-11-18T14:02:09.917Z"
}En onExit, el campo code del error usa los mismos códigos que la API. Los más comunes son:
| code | Qué pasó |
|---|---|
link_token_expired | El token venció antes de terminar. Crea uno nuevo y vuelve a abrir el widget. |
invalid_link_token | El token no existe o no tiene el formato correcto. |
link_token_used | El token ya se usó para crear una conexión. |
credentials_invalid | El banco rechazó las credenciales. |
action_required | El banco pide una acción en su sitio (por ejemplo actualizar datos o registrar el equipo). |
institution_unreachable | No pudimos comunicarnos con el banco. Se puede intentar más tarde. |
Mensajes postMessage
connect.js abre https://banky.cl/connect?token=…&origen=… en un iframe y escucha los mensajes que el widget envía con window.postMessage. Verifica que cada mensaje venga del origen https://banky.cl antes de usarlo.
| type | Datos | Cuándo |
|---|---|---|
BANKY_SUCCESS | { type, link } | La cuenta quedó conectada. |
BANKY_EXIT | { type, error? } | La persona cerró el widget o hubo un error que no se pudo resolver adentro. |
Abrir el widget sin el script
Si tu aplicación ya tiene su propio modal (o es una app móvil con una vista web), puedes cargar la URL del widget directamente y escuchar los mensajes tú mismo. El parámetro origen es el origen de tu página (esquema, dominio y puerto): el widget envía sus mensajes solo a ese origen.
iframe
<iframe
src="https://banky.cl/connect?token=lt_7c1e9a4f2b8d6035e1a7c94b2f0d8e6a1c3b5d7f9e2a4c6b&origen=https://tuapp.cl"
title="Conectar banco"
allow="clipboard-write"
></iframe>mensajes.js
window.addEventListener("message", (evento) => {
// Acepta solo mensajes del widget.
if (evento.origin !== "https://banky.cl") return;
const { type, link, error } = evento.data ?? {};
if (type === "BANKY_SUCCESS") guardarConexion(link.id);
if (type === "BANKY_EXIT") cerrarModal(error ?? null);
});Buenas prácticas
- Crea el link token justo antes de abrir el widget, no al cargar la página: vence a los 30 minutos.
- Usa
holder_type: "business"para cuentas de empresa. Hoy BCI Empresas solo acepta titulares de empresa. - Si quieres que la conexión esté disponible para agentes de IA, crea el token con
allow_mcp: truey explícale a la persona para qué. - Si el link pasa a
credentials_invalidoaction_required, pide a la persona que vuelva a conectar su cuenta con un token nuevo. No reintentes con las mismas credenciales: el banco podría bloquear la clave.