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 unlink_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.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
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:Re-abrir el widget para MFA
Cuando un sync requiere MFA async, elrefresh_intent.requires_mfa.widget_token contiene un ri_*_sec_* que abres igual que un wt_*:
onSuccess con et_* — el link ya existe, solo estamos resolviendo el MFA.