Qué es realmente un widget
Un Widget de Fluz es un flujo alojado, renderizado por Fluz, que incrustas en tu propio sitio con unas pocas líneas de JavaScript. Se ejecuta en tu dominio, bajo tu marca, ya sea en un modal sobre tu página o, por ahora solo en staging, de forma inline en un contenedor con el tamaño que definas. 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 scopes que necesita para actuar sobre esa cuenta. Sin otorgamiento, no hay acceso a la API.
Capturar datos sensibles
Los números de tarjeta, SSNs, documentos de identidad y PINs son recopilados por Fluz, dentro del entorno PCI DSS de Fluz, y cifrados de nuestro lado. Nunca tocan tus servidores.
Confirmar el 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 cual convierte un token preautorizado en una transacción completada.
El modelo mental: el widget es una superficie de consentimiento y de datos sensibles, no un producto. Es la parte angosta y de alto cumplimiento del flujo. La API es donde ocurre el trabajo.
La división del trabajo
Puedes ejecutar todo detrás de escena
Este es el punto más comúnmente pasado por alto sobre el widget: no es la única forma de usar Fluz, y no es la forma en que se realiza la mayor parte del trabajo. Una vez que un usuario ha otorgado scopes a tu aplicación — ya sea mediante el widget o mediante el flujo de otorgamiento OAuth independiente — tu servidor posee un token de acceso de usuario. A partir de ese momento, toda capacidad listada en la página de Características de la API está disponible para ti de forma programática, sin el widget abierto y sin un usuario mirando:Fuentes de fondos
Vincula tarjetas bancarias y cuentas bancarias de 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, bloqueo/desbloqueo, PINs, aprovisionamiento en billetera, emisión masiva.
Tarjetas open loop
Genera enlaces de tarjeta alojados que los destinatarios reclaman, 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 API”. La mayoría de las integraciones caen en algún 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, el inicio de sesión por 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 en sprints.
- Cero alcance PCI, cero manejo de datos CIP de tu lado.
- Menor control sobre la apariencia y sensación 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 hacer coincidir 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. Ver 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 (scopes de la app)
En la pestaña Permissions de tu aplicación, seleccionas los scopes que tu aplicación puede solicitar. Este es el máximo que tu app podrá pedir, independientemente de lo que un usuario individual acepte. Los scopes sin los cuales un tipo específico de widget no puede funcionar se agrupan al final de la pestaña y no se pueden deseleccionar.Consulta Scopes 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 adónde puede ir el otorgamiento (pestaña OAuth)
Origin — el dominio que aloja el widget. Redirect URIs — adonde nuestro servidor de autorización puede devolver al usuario, sin parámetros de consulta, y debe coincidir exactamente al 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 fija el piso (scopes de usuario)
Cuando se abre el widget, se le muestran al usuario los scopes que solicitaste — agrupados bajo encabezados legibles de alto nivel en lugar de listados como valores enum crudos — y los aprueba. Cualquier cosa que rechacen simplemente no se otorga.
4
Ambos otorgamientos deben estar activos
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 estar sin expirar. Esto se aplica en
generateUserAccessToken, no en tiempo de llamada — por lo que un otorgamiento revocado o vencido aparece 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 Basic auth de client_id:client_secret por un accessToken, un refreshToken y el arreglo scope confirmado. Consulta Intercambiar un código de autorización y Actualizar 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, enviando a nuestros servidores, bajo nuestro programa de cumplimiento. Eso significa que Fluz se responsabiliza de:- Datos de tarjeta. Los PANs, fechas de vencimiento y CVVs se capturan y almacenan conforme a los requisitos de PCI DSS y se cifran en reposo de nuestro lado. Tu página nunca los ve, tus logs nunca los contienen y tu infraestructura permanece fuera del alcance PCI para estos flujos.
- Revelación completa de tarjeta. Mostrar a un usuario final el número de su propia tarjeta virtual ocurre en una superficie alojada por Fluz — ya sea dentro del widget o inline en tu propia página mediante Secure Elements Card Reveal. En cualquier caso, los datos se renderizan en el frame de Fluz, no en el tuyo, por lo que te mantienes fuera del alcance PCI. Llevar el PAN y CVV en crudo a tus propios servidores es el único camino que requiere una certificación PCI DSS — ver Due diligence.
- Datos CIP e identidad. SSNs, fechas de nacimiento, direcciones y documentos de identidad cargados se recopilan y retienen dentro de nuestro entorno de verificación.
- PINs. Establecidos y almacenados por nosotros, nunca transmitidos a ti.
- Credenciales bancarias. Los flujos de Plaid Link se ejecutan dentro del widget; tú nunca manejas el login bancario del usuario.
apiSecret y client_secret. La pestaña de 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 conforme a los requisitos de PCI DSS. Si tu equipo de cumplimiento necesita documentación para una revisión de proveedores, contacta a tu account manager de Fluz.
Obtener tu código de embed
No escribes la integración a mano. La pestaña Installation de tu aplicación la genera por ti, prellenada con elapiKey real de tu app, y te ofrece dos selectores:
Transaction Type — elige la dirección del movimiento de dinero:
No todos los tipos de widget mueven dinero.
ENROLLMENT guía a un usuario por la configuración de cuenta — verificación de identidad, fuentes de fondos, PIN — en el orden que elijas, sin monto y sin confirmación de transacción. Actualmente está disponible solo en staging.
Server Language — el snippet que genera el token firmado de transacción preaprobada, en el lenguaje que realmente usa tu backend:
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 por completo 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, vincular el modal a un botón que ya tengas o, por ahora solo en staging, omitir el modal por completo y renderizar el widget inline en un contenedor con el tamaño que definas. Consulta Agregar el widget JS 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 empiezas desde una app en blanco. Desde el panel de desarrollador, elige Browse templates y selecciona la que más se acerque a lo que estás construyendo. Una plantilla preconfigura el tipo de app, los scopes requeridos, la dirección de la transacción y la secuencia de pantallas que verá el usuario, de modo que una app nueva sea funcional en el momento en que terminas de nombrarla. Las plantillas disponibles hoy incluyen:Trata la plantilla como un punto de partida, no como una especificación. Después de crearla, ve a la pestaña Permissions y moldea la app en torno a lo que realmente intentas hacer — agrega los scopes que tu caso de uso necesita, elimina 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 scopes 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.Qué ve el usuario final
Una vez que un usuario llega a una página que aloja 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 saber qué significa cada una y cuántos intentos obtiene un usuario.3
Otorgar permisos
El usuario revisa y aprueba los scopes que solicitó tu app.
4
Establecer un PIN
Una medida de seguridad a nivel 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 hacia 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. Pon 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
Scopes, orígenes, URIs de redirección, webhooks.
Configura tu servidor
Genera el token de transacción preaprobada en tu lenguaje.
Incrustar el widget
Etiqueta de script, llamada de init, vinculación de botón.
Widget de enrollment
Ejecuta KYC, fuentes de fondos y PIN en el orden que elijas. Solo en staging por ahora.
Secure Elements
Muestra detalles de tarjeta inline en tu propia página, sin el modal del widget.
Terminar una sesión
Cancela un pago que ya entregaste, antes de que el usuario lo complete.
Todo lo que puede hacer la API
La superficie completa de capacidades, toda disponible del lado del servidor.
Construir una plataforma
Ejecuta cada capacidad en cuentas conectadas con tokens con alcance de cliente.