Widget de Inscripción

El tipo de widget ENROLLMENT guía a un usuario por la configuración de su cuenta inmediatamente después de autorizar tu aplicación. Tiene la misma estructura que los demás tipos de widget — el usuario es redirigido directamente a una tarea después de autorizar — con una diferencia: tú eliges qué pasos de configuración verá el usuario. A diferencia de los tipos de payout y pay-in, este widget no mueve dinero. No hay monto a confirmar ni transacción que aprobar.

ENROLLMENT está disponible actualmente solo en staging. La compatibilidad con producción está en camino; hasta entonces, un token de producción con transactionType: "ENROLLMENT" será rechazado.

Requisitos previos

Una aplicación de widget con la configuración de OAuth lista. Consulta Configurar App Widget. Cualquier tipo de aplicación puede ejecutar este widget, incluyendo una app de OAuth Integration solo de permisos.
El usuario debe haber otorgado los alcances (scopes) de tu aplicación. Los scopes se verifican para la aplicación en su conjunto, no por paso. Si falta alguno, el widget envía al usuario a la pantalla de consentimiento de OAuth antes del primer paso, igual que los otros tipos de widget. Ningún paso se omite o falla por causa de un scope.
Un usuario de OAuth y un token de acceso, igual que en los otros tipos de widget.

Elegir los pasos

Pasa un arreglo ordenado steps en el token de transacción preaprobada junto con transactionType: "ENROLLMENT":

import jwt from 'jsonwebtoken';

const generatedToken = jwt.sign(
  {
    apiKey: '', // Your apiKey
    transactionType: 'ENROLLMENT',
    externalId: '', // Your unique identifier for the user
    steps: ['KYC', 'FUNDING_SOURCE', 'PIN'],
    jti: uuidv4(),
  },
  secret, // Your apiSecret
  { expiresIn: '1 day' }
);

amount no es obligatorio para este tipo de widget. Todo lo demás sobre el token permanece igual — consulta Configura tu servidor.

Pasos compatibles

Paso	Lo que hace el usuario
`KYC`	Completa la verificación de identidad personal, escalando a captura de documentos si es necesario. Consulta Verificar por Widget.
`FUNDING_SOURCE`	Vincula una o más fuentes de fondos — una cuenta bancaria vía Plaid, una tarjeta bancaria o PayPal.
`PIN`	Configura su PIN de transacción de Fluz.

Este widget ejecuta solo verificación de identidad personal. La verificación de negocio (KYB) no es uno de sus pasos — usa el tipo de widget KYB dedicado para eso. Consulta Registro de negocios.

Orden

Los pasos se ejecutan en el orden en que los listes. Fluz no los reordena, y no hay combinaciones inválidas — ninguno de los tres pasos es un prerrequisito de otro, por lo que ["PIN", "FUNDING_SOURCE", "KYC"] es tan válido como ["KYC", "FUNDING_SOURCE", "PIN"]. Enumera los pasos en el orden que tenga sentido para tu producto.

Comportamiento de omisión

Un paso que el usuario ya haya cumplido se omite silenciosamente — nunca ve su pantalla.

Paso	Se omite cuando
`KYC`	El usuario ya aprobó la verificación de identidad
`PIN`	El usuario ya tiene un PIN configurado
`FUNDING_SOURCE`	Nunca

El paso de fuente de fondos nunca se omite, porque un usuario que ya tiene una fuente puede querer agregar otra. Siempre se muestra, y el usuario decide cuándo continuar. Si cada paso que solicitaste ya está cumplido, el widget se completa de inmediato sin mostrar una pantalla de paso.

Debido a que FUNDING_SOURCE nunca se omite automáticamente, una lista steps que lo incluya siempre mostrará al menos una pantalla. Si quieres que el resultado “nada que hacer, completar de inmediato” sea alcanzable, solicita solo KYC y PIN.

El paso de fuente de fondos

Este paso es deliberadamente abierto. El usuario puede agregar tantas fuentes de fondos como desee en una sola visita — la pantalla enumera lo que ha agregado hasta el momento y tiene un control explícito de Continuar, así que avanzar es su decisión en lugar de algo que ocurra automáticamente tras el primer enlace exitoso. Un usuario que no quiera agregar nada puede continuar sin añadir una fuente. Los cambios de fuente de fondos aún no emiten un webhook. Hay un evento dedicado en progreso. Hasta que esté disponible, lee las fuentes de fondos del usuario con la consulta getWallet después de que el flujo se complete. Consulta Fuentes de fondos.

Finalización

Cuando el último paso se resuelve, el widget muestra una pantalla de finalización. Si proporcionaste un callbackUrl, incluye un botón de regreso a tu aplicación; de lo contrario ofrece un control Listo que cierra el widget.

No infieras éxito por el cierre del widget — un usuario puede descartarlo en cualquier momento. Confía en los callbacks onSuccess y onError, y en los webhooks de los pasos individuales: los eventos de verificación de identidad se disparan independientemente del widget. Consulta Webhooks.

Tokens rechazados

La reclamación steps se valida cuando la sesión se abre. Todos estos casos rechazan la sesión en lugar de degradarla a un flujo parcial:

Problema	Resultado
`steps` ausente por completo	Error de parámetro faltante
`steps` no es un arreglo, o está vacío	Error de parámetro inválido
`steps` contiene un valor que no es `KYC`, `FUNDING_SOURCE` o `PIN`	Error de parámetro inválido que nombra el valor no compatible y enumera los compatibles
`steps` lista el mismo paso dos veces	Error de parámetro inválido que nombra el duplicado

El usuario ve una pantalla genérica de “enlace de widget inválido” — la razón específica no se le muestra, ya que un token mal formado es un problema de integración y no algo sobre lo que pueda actuar. Revisa tu generador de tokens y consulta el detalle del error entregado a tu callback onError.

Próximos pasos

Configura tu servidor

Genera el token de transacción preaprobada en tu lenguaje.

Incorpora el widget

Script tag, llamada a init, callbacks.

Verificar por widget

Lo que experimenta el usuario durante el paso de KYC.

Fuentes de fondos

Lo que puedes hacer con una fuente cuando ya está vinculada.

​Elegir los pasos

​Pasos compatibles

​Orden

​Comportamiento de omisión

​El paso de fuente de fondos

​Finalización

​Tokens rechazados

​Próximos pasos

Configura tu servidor

Incorpora el widget

Verificar por widget

Fuentes de fondos

Elegir los pasos

Pasos compatibles

Orden

Comportamiento de omisión

El paso de fuente de fondos

Finalización

Tokens rechazados

Próximos pasos