Widget de registro

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

ENROLLMENT está disponible actualmente solo en staging. El soporte para 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 en su lugar. Ver Configurar App Widget. Cualquier tipo de aplicación puede ejecutar este widget, incluido un app de solo permisos OAuth Integration.
El usuario debe haber otorgado los alcances (scopes) de tu aplicación. Los scopes se verifican para la aplicación en su totalidad, no por paso. Si falta alguno, el widget envía al usuario por 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 falta de un scope.
Un usuario de OAuth y un token de acceso, igual que 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 requerido para este tipo de widget. Todo lo demás del token permanece igual — ver Configura tu servidor.

Pasos compatibles

Paso	Qué hace el usuario
`KYC`	Completa la verificación de identidad personal, escalando a captura de documentos si es necesario. Ver 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. Ver Registro de Negocios.

Orden

Los pasos se ejecutan en el orden en que los enumeres. Fluz no los reordena, y no hay combinaciones inválidas — ninguno de los tres pasos es un prerrequisito de otro, así 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 en silencio — 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 avanzar. Si todos los pasos que solicitaste ya están satisfechos, 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 inmediatamente” 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 quiera en una sola visita — la pantalla lista lo que ha agregado hasta el momento y muestra un control explícito de Continuar, por lo que avanzar es su decisión en lugar de algo que ocurra automáticamente tras el primer vínculo exitoso. Un usuario que no quiera agregar nada puede continuar sin añadir una fuente. Los cambios en fuentes de fondos aún no emiten un webhook. Un evento dedicado está en progreso. Hasta que se lance, lee las fuentes de fondos del usuario con la consulta getWallet después de que el flujo complete. Ver 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 para los pasos individuales: los eventos de verificación de identidad se disparan independientemente del widget. Ver Webhooks.

Un registro que incluye KYC solo se completa una vez que la verificación de identidad pasa. Cuando una verificación falla, onError se dispara con US-0005 y onSuccess no se dispara para ese intento. Lo que suceda después depende de dónde falló: una verificación que termina sin más pasos que ofrecer deja al usuario en el formulario, donde un reintento que pase aún completa el registro y dispara onSuccess una vez; una cuenta que entra en revisión muestra la pantalla de revisión en su lugar, y esa sesión no puede completarse. De cualquier forma, trata US-0005 como “aún no verificado” en lugar de una respuesta final, y confirma el resultado desde el webhook KYC_STATUS_UPDATE — que te llega solo si tu aplicación y la concesión del usuario tienen el scope VERIFY_KYC. Ver Callbacks de resultado.

Tokens rechazados

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

Problema	Resultado
`steps` faltante 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 nombrando el valor no compatible y listando los compatibles
`steps` lista el mismo paso dos veces	Error de parámetro inválido nombrando 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

Etiqueta de script, llamada de 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 una vez 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