Saltar al contenido

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

  1. 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_name del link token o, si no lo enviaste, el de tu organización.
  2. Banco. Lista de instituciones con su estado; las que están próximamente aparecen deshabilitadas.
  3. 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.
  4. 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.
  5. 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_token creado 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 null si 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:

codeQué pasó
link_token_expiredEl token venció antes de terminar. Crea uno nuevo y vuelve a abrir el widget.
invalid_link_tokenEl token no existe o no tiene el formato correcto.
link_token_usedEl token ya se usó para crear una conexión.
credentials_invalidEl banco rechazó las credenciales.
action_requiredEl banco pide una acción en su sitio (por ejemplo actualizar datos o registrar el equipo).
institution_unreachableNo 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.

typeDatosCuá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: true y explícale a la persona para qué.
  • Si el link pasa a credentials_invalid o action_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.