Primeros pasos
Inicio rápido
En esta guía conectas una cuenta del Banco de Prueba y lees sus movimientos. Todo ocurre en modo test, con datos ficticios, así que puedes repetirla las veces que quieras.
Necesitas:
- Acceso al panel de Banky (entras con tu cuenta de Google).
- Un servidor propio donde guardar la llave secret. Los ejemplos usan Node.js 18 o superior, pero cualquier lenguaje sirve.
Crea una llave de API
En el panel, deja apagado el interruptor Modo producción (así trabajas en modo test), entra a API keys y crea una llave secret. Se muestra una sola vez: cópiala y guárdala como variable de entorno en tu servidor.
.env
BANKY_SECRET_KEY=banky_sk_test_…Crea un link token
Cada vez que una persona va a conectar su banco, tu servidor crea un link token. Indica si la cuenta es de empresa (business) o de persona (individual) y, si quieres, el nombre que verá la persona en el widget.
curl -X POST "https://api.banky.cl/v1/link_tokens" \
-H "Authorization: Bearer $BANKY_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"holder_type": "business",
"client_name": "Contable Austral"
}'Respuesta
201{
"object": "link_token",
"link_token": "lt_7c1e9a4f2b8d6035e1a7c94b2f0d8e6a1c3b5d7f9e2a4c6b",
"expires_at": "2026-11-18T14:31:52.104Z",
"mode": "test"
}En una aplicación real lo normal es exponer un endpoint propio que devuelva el token a tu frontend:
servidor.js
// servidor.js (Node.js 18 o superior, con Express)
import express from "express";
const app = express();
app.use(express.json());
// Tu frontend llama a este endpoint para obtener un link token nuevo cada vez que abre el widget.
app.post("/api/link-token", async (req, res) => {
const respuesta = await fetch("https://api.banky.cl/v1/link_tokens", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BANKY_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ holder_type: "business", client_name: "Contable Austral" }),
});
if (!respuesta.ok) return res.status(502).json({ error: "No se pudo crear el link token" });
const { link_token } = await respuesta.json();
res.json({ link_token });
});
app.listen(3000);Abre el widget
Carga connect.js en tu página y abre el widget con el token. El widget se muestra en un modal sobre tu aplicación; la persona elige su banco e ingresa sus credenciales.
index.html
<button id="conectar">Conectar mi banco</button>
<script src="https://banky.cl/connect.js"></script>
<script>
document.getElementById("conectar").addEventListener("click", async () => {
const { link_token } = await fetch("/api/link-token", { method: "POST" }).then((r) => r.json());
Banky.open({
token: link_token,
onSuccess: (link) => {
// Guarda link.id junto al usuario o la empresa en tu base de datos.
fetch("/api/conexiones", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ link_id: link.id }),
});
},
onExit: (error) => {
if (error) console.warn("La conexión no se completó:", error);
},
});
});
</script>En modo test, elige Banco de Prueba e ingresa el RUT 11.111.111-1 con la clave banky. Para una cuenta de empresa, el widget pide además el RUT de la empresa: usa cualquier RUT válido, como 76.123.874-4. En Modo test están todas las credenciales de prueba.
Recibe la conexión
Cuando la conexión termina, onSuccess recibe el objeto link. Guarda su id: lo necesitas para leer los datos. Las cuentas y los últimos 90 días de movimientos ya quedaron leídos en ese momento.
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"
}Si configuraste webhooks, además recibes link.created y, si hubo movimientos, movements.new. Usa los webhooks como fuente de verdad: onSuccess depende de que la persona mantenga abierta tu página.
Lee cuentas y movimientos
Lista las cuentas de la conexión:
curl "https://api.banky.cl/v1/accounts?link_id=link_9f2c41ab7e05d318" \
-H "Authorization: Bearer $BANKY_SECRET_KEY"Respuesta
200{
"object": "list",
"data": [
{
"id": "acc_3f9a1c0e5b7d2468",
"object": "account",
"link_id": "link_9f2c41ab7e05d318",
"number": "0012785975",
"name": "Cuenta Corriente",
"type": "checking_account",
"currency": "CLP",
"balance": {
"available": 26593700,
"current": 26638700
},
"refreshed_at": "2026-11-18T14:02:11.204Z"
}
],
"has_more": false
}Y luego los movimientos de una cuenta, del más nuevo al más antiguo:
curl "https://api.banky.cl/v1/accounts/acc_3f9a1c0e5b7d2468/movements?since=2026-11-01&limit=50" \
-H "Authorization: Bearer $BANKY_SECRET_KEY"Respuesta
200{
"object": "list",
"data": [
{
"id": "mov_e41b9c07a2d85f36",
"object": "movement",
"account_id": "acc_3f9a1c0e5b7d2468",
"amount": 1315000,
"currency": "CLP",
"type": "inflow",
"description": "Pago de factura de Constructora Valle Central SpA",
"bank_description": "TRASPASO DE: CONSTRUCTORA VALLE CENTRAL SPA",
"post_date": "2026-11-18",
"transaction_date": "2026-11-18",
"counterparty": {
"name": "Constructora Valle Central SpA",
"id": "76287005-3"
},
"reference_id": "479249273"
}
],
"has_more": true
}Los montos vienen en pesos enteros: positivos para abonos y negativos para cargos. Si has_more es true, pide la página siguiente con starting_after (ver Paginación).
Pasar a producción
- Crea una llave secret live y cámbiala en tu servidor. El código no cambia.
- Registra un endpoint de webhooks live y verifica la firma de cada evento.
- Revisa qué bancos están disponibles en Instituciones: hoy en live se conecta BCI Empresas.
- Maneja los estados
credentials_invalidyaction_required: en esos casos la persona debe volver a conectar su cuenta con el widget.