Qué es realmente un widget
Un Widget de Fluz es un flujo hospedado y renderizado por Fluz que embeberás en tu propio sitio con unas pocas líneas de JavaScript. Se ejecuta en un modal sobre tu página, en tu dominio, bajo tu marca. Existe para hacer tres trabajos que no deberías tener que construir tú mismo:Recopilar el permiso del usuario
El widget es cómo un usuario final crea o inicia sesión en su cuenta de Fluz y otorga a tu aplicación los alcances que necesita para actuar sobre esa cuenta. Sin otorgamiento, no hay acceso a la API.
Capturar datos sensibles
Números de tarjeta, SSN, documentos de identidad y PIN se recopilan por Fluz, dentro del entorno PCI DSS de Fluz, y se cifran de nuestro lado. Nunca tocan tus servidores.
Confirmar movimiento de dinero
El usuario ve y aprueba el monto y la dirección de una transferencia en una superficie en la que puede confiar, lo que convierte un token preautorizado en una transacción completada.
El modelo mental: el widget es una superficie de consentimiento y datos sensibles, no un producto. Es la parte estrecha y de alto cumplimiento del flujo. La API es donde sucede el trabajo.
La división del trabajo
Puedes ejecutar todo detrás de escena
Este es el punto que más suele pasarse por alto sobre el widget: no es la única forma de usar Fluz, y no es la forma en que se hace la mayor parte del trabajo. Una vez que un usuario ha otorgado alcances a tu aplicación — ya sea a través del widget o mediante el flujo de otorgamiento OAuth independiente — tu servidor posee un token de acceso de usuario. A partir de ese momento, todas las capacidades listadas en la página de Funciones de la API están disponibles para ti de forma programática, sin widget abierto y sin usuario mirando:Fuentes de fondos
Vincula tarjetas bancarias y cuentas bancarias Plaid, luego extrae fondos bajo demanda.
Billeteras y transferencias
Abre cuentas de gasto, deposita, retira y mueve fondos internamente o entre cuentas.
Tarjetas virtuales
Controles de gasto, bloquear/desbloquear, PIN, aprovisionamiento a billeteras, emisión masiva.
Tarjetas open loop
Genera enlaces de tarjeta hospedados que los destinatarios canjean, con control total del ciclo de vida del enlace.
Enviar dinero
Busca destinatarios por teléfono o email y transfiere a otras billeteras de Fluz.
Aprobaciones y usuarios autorizados
Agrega miembros del equipo, emíteles tarjetas y enruta solicitudes de aprobación.
Elige cuánto del flujo nos entregas
No tienes que elegir “todo widget” o “toda la API”. La mayoría de las integraciones caen en un punto intermedio, y el factor decisivo suele ser qué datos sensibles ya posees y quieres seguir poseyendo.- Widget completo
- Híbrido (el más común)
- Headless / solo API
Nos entregas todo el recorrido del usuario.El widget maneja la creación de cuenta, inicio de sesión con teléfono + 2FA, KYC, configuración de PIN, el otorgamiento de permisos y la confirmación de la transacción. Tú renderizas un botón y generas un token firmado.
- Camino más rápido a producción — medido en horas, no sprints.
- Cero alcance PCI, cero manejo de datos CIP de tu lado.
- Menor control sobre el look and feel entre el clic y el callback.
Sobre registrar usuarios vía API: si registras y haces KYC a un usuario tú mismo y luego abres el widget, pasa
externalId en el token de transacción preaprobada para que podamos asociar la sesión con la cuenta que ya creaste en lugar de iniciar una nueva. También puedes pasar phoneNumber, firstName, lastName, email y username para omitir los pasos correspondientes en el widget. Consulta Configura tu servidor.Cómo se relacionan los widgets con las aplicaciones OAuth
Un widget es una aplicación OAuth. No es un objeto separado con un modelo de permisos separado — es una app OAuth que incluye un front-end embebible.1
Defines el techo (alcances de la app)
En la pestaña Permissions de tu app, seleccionas los alcances que tu aplicación puede solicitar. Este es el máximo que tu app podrá pedir, sin importar lo que cualquier usuario individual acepte. Los alcances sin los cuales un tipo de widget no puede funcionar están agrupados al final de la pestaña y no se pueden deseleccionar.Revisa Alcances de la aplicación para la lista completa —
MAKE_DEPOSIT, MAKE_WITHDRAW, LIST_PAYMENT, CREATE_VIRTUALCARD, REVEAL_VIRTUALCARD, PURCHASE_GIFTCARD y el resto.2
Configuras a dónde puede ir el otorgamiento (pestaña OAuth)
Origin — el dominio que hospeda el widget. Redirect URIs — a dónde nuestro servidor de autorización puede regresar al usuario, sin parámetros de query, y debe coincidir exactamente en el momento del intercambio. Webhook URLs — uno o varios endpoints REST, cada uno opcionalmente suscrito a eventos específicos; una URL sin eventos seleccionados se convierte en un catch-all.Consulta Configurar App Widget.
3
El usuario establece el piso (alcances de usuario)
Cuando se abre el widget, se le muestran al usuario los alcances que solicitaste — agrupados bajo encabezados legibles de alto nivel en lugar de enumeraciones crudas — y los aprueba. Cualquier cosa que rechacen simplemente no se concede.
4
Ambos otorgamientos deben estar vigentes
Los permisos efectivos de una aplicación son la intersección del otorgamiento a nivel de app y el otorgamiento a nivel de usuario, y ambos deben no estar vencidos. Esto se aplica en
generateUserAccessToken, no en tiempo de llamada — por lo que un otorgamiento revocado o caducado se manifiesta como una falla de token, no como un error misterioso a mitad de flujo.5
El código se convierte en tokens
El otorgamiento produce un
code de autorización en tu URI de redirección. Intercámbialo en /token/exchange con un header de autenticación Basic de client_id:client_secret por un accessToken, un refreshToken y el arreglo scope confirmado. Consulta Intercambiando un código de autorización y Actualizando un token de acceso.Cumplimiento PCI y datos sensibles
Cuando el widget está abierto, los campos sensibles dentro de él son de Fluz, no tuyos. El usuario está escribiendo en nuestro iframe, publicando a nuestros servidores, bajo nuestro programa de cumplimiento. Eso significa que Fluz asume responsabilidad por:- Datos de tarjeta. Los PAN, fechas de expiración y CVV se capturan y almacenan de acuerdo con los requisitos PCI DSS y se cifran en reposo de nuestro lado. Tu página nunca los ve, tus logs nunca los contienen y tu infraestructura se mantiene fuera del alcance PCI para estos flujos.
- Revelado completo de tarjeta. Mostrar a un usuario final su propio número de tarjeta virtual es una superficie hospedada de Fluz por la misma razón.
- Datos CIP e identidad. SSN, fechas de nacimiento, direcciones y documentos de identidad cargados se recopilan y retienen dentro de nuestro entorno de verificación.
- PIN. Configurados y almacenados por nosotros, nunca transmitidos a ti.
- Credenciales bancarias. Los flujos de Plaid link se ejecutan dentro del widget; nunca manejas el login bancario del usuario.
apiSecret y client_secret. La pestaña Installation renderiza fragmentos funcionales que contienen tus credenciales reales, lo cual es conveniente y también un riesgo — genera el patToken en tu servidor, nunca en JavaScript del navegador. Cualquier cosa en el código fuente de tu página es pública.
Fluz mantiene controles SOC 2 Tipo II y maneja datos de tarjeta de acuerdo con los requisitos PCI DSS. Si tu equipo de cumplimiento necesita documentación para una revisión de proveedor, contacta a tu account manager de Fluz.
Obteniendo tu código de embed
No escribes la integración a mano. La pestaña Installation de tu app la genera por ti, precargada con elapiKey real de tu app, y te da dos selectores:
Transaction Type — elige la dirección del movimiento de dinero:
Server Language — el fragmento que genera el token de transacción preaprobada firmado, en el lenguaje que tu backend realmente usa:
JavaScript
Ruby
Python
Go
Java
PHP
C# / .NET
Más
apiSecret desde tu almacén de secretos y tendrás un generador de tokens funcional. Cada variante también está documentada en detalle en Configura tu servidor.
La parte del lado del cliente es una sola etiqueta de script más una llamada a FluzEmbedded.init(...). Puedes dejarnos renderizar el botón o vincular el modal a un botón que ya tengas. Consulta Agregar el JS Widget a tu página.
La configuración de tu app vive en:
https://fluz.app/for-developers/overview/19be9561-a6a1-4e02-8243-10ede908ef33. Las pestañas en la parte superior — Overview, Permissions, OAuth, Installation — mapean exactamente a los pasos anteriores.
Comienza desde una plantilla
No comienzas desde una app en blanco. Desde el panel de desarrollador, elige Browse templates y selecciona la más cercana a lo que estás construyendo. Una plantilla preconfigura el tipo de app, los alcances requeridos, la dirección de la transacción y la secuencia de pantallas que verá el usuario — por lo que una app nueva es funcional en el momento en que terminas de nombrarla. Las plantillas disponibles hoy incluyen:Trata la plantilla como un punto de partida, no una especificación. Después de crearla, ve a la pestaña Permissions y moldea la app según lo que realmente intentas hacer — agrega los alcances que tu caso de uso necesita, quita los que no. Un widget de payout que luego emitirá tarjetas en nombre del usuario necesita
CREATE_VIRTUALCARD; uno que solo mueve efectivo no. Solicitar menos alcances significa una pantalla de consentimiento más corta y una mayor tasa de finalización, así que pide lo que necesitas y nada más.Lo que ve el usuario final
Una vez que un usuario llega a una página que hospeda tu widget y realiza la acción que abre el modal:1
Iniciar sesión o registrarse
El usuario se autentica en su cuenta de Fluz con un código 2FA enviado a su teléfono. Si no tiene una cuenta, la crea aquí. Pasar
phoneNumber en el patToken salta directamente al paso de ingreso del código.2
KYC
Si ya posees el SSN del usuario, pásanoslo y lo validamos. Si no, el widget ejecuta el flujo KYC completo. Las respuestas son
APPROVED, DECLINED, DUPLICATE o ERROR — consulta Verificación KYC de usuario para ver qué significa cada una y cuántos intentos obtiene un usuario.3
Otorgar permisos
El usuario revisa y aprueba los alcances que solicitó tu app.
4
Configurar un PIN
Una medida de seguridad a nivel de Fluz, solicitada nuevamente más adelante para acciones que requieren confirmación elevada.
5
Confirmar la transacción
El usuario ve el monto y la dirección y aprueba o descarta. En cualquier caso, recibes un evento.
Pay-In: fondos hacia tu plataforma
Verifica primero el saldo de Fluz del usuario para confirmar que puede cubrir la transacción.
- El usuario ingresa un monto de depósito y hace clic en tu botón.
- El widget presenta una pantalla de confirmación.
- Confirmado → iniciamos la transferencia desde la cuenta de gasto del usuario a la tuya.
- Denegado o descartado → enviamos un evento.
- Recibes un evento de finalización o de falla.
- Verifica tu propio saldo de Fluz para confirmar la liquidación.
Payout: fondos hacia tu usuario
Verifica primero el saldo de Fluz de tu cuenta. Si no puedes cubrir la transferencia, inicia un depósito desde tu fuente de fondos. Pone en cuarentena o retén los fondos del usuario de tu lado para evitar doble gasto mientras la transferencia está en curso.
- El usuario ingresa un monto de retiro y hace clic en tu botón.
- El widget presenta una pantalla de confirmación.
- Confirmado → iniciamos la transferencia desde tu cuenta de gasto de operador a la del usuario.
- Denegado o descartado → enviamos un evento.
- Recibes un evento de finalización o de falla.
- El widget muestra al usuario que su retiro está completo y le da acceso directo a su tarjeta virtual de Fluz.
Cada llamada que mueve dinero necesita un
jti único en el token para idempotencia, y un idempotencyKey único del lado de la API. Consulta Idempotencia.Próximos pasos
Agregar un widget
Crea tu primera app desde una plantilla.
Configurar OAuth y permisos
Alcances, orígenes, URIs de redirección, webhooks.
Configura tu servidor
Genera el token de transacción preaprobada en tu lenguaje.
Embeber el widget
Etiqueta de script, llamada init, vinculación de botón.
Todo lo que puede hacer la API
Toda la superficie de capacidades, disponible del lado del servidor.
Construir una plataforma
Ejecuta cada capacidad en cuentas conectadas con tokens con alcance de cliente.