Skip to main content
Algunos bancos chilenos (Santander, BCI, BancoEstado a veces) requieren clave dinámica en cada sync. Eso significa que cuando creas un refresh_intent, el banco pide MFA y el sync no puede completarse hasta que el user lo resuelva. Rail maneja esto de forma asíncrona: el intent queda en status: requires_mfa con un widget_token listo para abrir. Tu app debe reabrir el widget para que el user meta el código.

Flow completo

Paso a paso

1. Backend — crea el refresh intent

2. Backend — handler del webhook

3. Frontend — escuchar notificación + abrir widget

Alternativa: polling (sin webhooks)

Si no tienes webhooks setup todavía, puedes polear el intent:
No polees más rápido que cada 5 segundos. Si excedes 100 req/min vas a tirar 429. Ver Rate limits.

Casos edge

El widget_token expiró antes de que el user lo abra

requires_mfa.expires_at es 10 minutos desde la emisión. Si el user no abrió el widget a tiempo:
  • El próximo refresh_intent crea un nuevo widget_token.
  • El intent viejo queda en status: failed con error_code: requires_mfa_user_timeout.
Muéstrale al user un botón “Reintentar” que dispare un nuevo POST /v1/refresh_intents.

El user resuelve el MFA pero el banco lo rechaza

El sync sigue su curso server-side y termina en status: failed con error_code: rejected_credentials. Eso significa que la clave dinámica fue inválida. Pídele que reintente.

El user cierra el widget sin resolver

onExit(reason) recibe 'user_close'. El intent queda en requires_mfa hasta que expire (10min). Si quieres cancelar antes:

UX recomendada

  • Muestra un estado claro: “Esperando código del banco” mientras está en requires_mfa.
  • Botón cancelar: deja al user salir del flow sin que quede colgado.
  • Texto del banco: si sabes que el banco pide MFA en cada sync (Santander, BCI), avísalo upfront: “Tu banco va a pedirte un código cada vez que sincronicemos”.
  • Recordatorio app del banco: “Abre tu app de Santander para ver el código”.
  • Timeout visual: countdown del expires_at para que el user sepa cuánto le queda.