Skip to main content

Por qué un widget

Tu app nunca debe ver las credenciales bancarias del user. El widget de Rail Connect es un iframe que las captura directamente, las manda encriptadas a Rail, y te devuelve un link_id opaco.

Flow completo

Setup

1. Backend — emite el widget token

¿Cuenta de empresa? Envía holder_type: "business" en el body del POST /v1/widget_tokens. El widget muestra el form de empresa (RUT empresa + RUT persona + clave) y filtra el picker a los bancos que soportan empresa. El frontend no cambia. Ver Banca empresa.

2. Frontend — abre el widget

3. Backend — canjea el exchange token

Configuración avanzada

Pre-fill de RUT y nombre

Si ya conoces el RUT del user (porque está logueado en tu app), pre-cárgalo en el widget. Esto ahorra fricción y mejora conversión.
Pre-fillear el RUT mejora la conversión entre 2-4% según nuestros tests internos. Si tu app ya lo conoce, úsalo siempre con editable: false.

Velocidad de conexión (release_mode)

El widget es Fintoc-style: devuelve el et_ y se cierra en un punto del sync, y el resto de la data sigue poblándose en background (la recibís por webhooks o polling a GET /v1/accounts). Dónde se cierra lo elegís al crear el token, con release_mode en POST /v1/widget_tokens:
El tramo “login + productos” es el grueso del tiempo de conexión, así que release_mode: "login" cierra el widget bastante antes. Elegilo si tu UX prioriza velocidad y tu backend ya consume los webhooks (refresh_intent.accounts_synced, refresh_intent.transactions_synced) o poolea el estado del refresh intent. Si preferís que la data esté lista al cerrar el widget, omitilo (o usá "accounts").
En conexiones multi-banco (connection_limit > 1) el cierre en login ya es implícito —para que el user encadene el siguiente banco sin esperar—, así que ahí release_mode no cambia nada.

Appearance (dark mode)

'auto' respeta el prefers-color-scheme del browser del user.

Locale

Hoy solo soportamos español chileno y español neutro. Inglés en roadmap.

Soporte en el widget

Cuando una conexión falla en algo que tu usuario no puede resolver solo, el widget le ofrece tu contacto de soporte (nunca el de Rail). Se configura una vez en el dashboard, en Configuración → Empresa → Soporte en el widget: WhatsApp, email y/o centro de ayuda. Si no cargás ninguno, el widget no muestra nada. El link no aparece en todos los errores, a propósito: Cuando el canal es WhatsApp, el mensaje va prellenado con el banco, el nombre de tu app y un código de referencia del intento — que es lo primero que tu equipo necesita y lo que el usuario no sabe contestar. Nunca incluye RUT ni nada de la clave.
Si preferís manejarlo por tu cuenta, no cargues ningún contacto: el widget te sigue avisando cada falla por onEvent / onError con el code y el institution_id, y mostrás tu propia UI.

Callbacks

Listen to widget events

Para analytics o tracking del funnel, suscríbete a todos los eventos del widget:
Estos eventos son solo para UX/analytics. No los uses para confirmar que el link fue creado o que el sync funcionó — para eso usa webhooks o el onSuccess con el exchange token. Los eventos del widget pueden perderse (user cierra el browser, network) y no garantizan delivery.

Re-abrir el widget para MFA

Cuando un sync requiere MFA async, el refresh_intent.requires_mfa.widget_token contiene un ri_*_sec_* que abres igual que un wt_*:
No hace falta onSuccess con et_* — el link ya existe, solo estamos resolviendo el MFA.