Agregar el widget JS a tu página

Antes de comenzar: tu servidor debe generar un patToken para cada sesión y ponerlo a disposición de tu página. Consulta Configura tu servidor.

Agrega este cargador a tu página. Inyecta el script del widget y se resuelve una vez que FluzEmbedded está listo, por lo que el resto de tu código nunca se ejecuta antes de que el widget exista.

<script>
  function loadFluzWidget() {
    return new Promise((resolve, reject) => {
      const get = () => (typeof FluzEmbedded !== "undefined" ? FluzEmbedded : null);
      if (get()) return resolve(get());

      const script = document.createElement("script");
      script.src =
        "https://storage.googleapis.com/fluz-fluz-file-uploads-prod-ricuyxowbwlfprel/widgets/fluz-embedded-payment-widget.js?v1.1.1";
      script.async = true;
      script.onload = () =>
        get() ? resolve(get()) : reject(new Error("FluzEmbedded is not available"));
      script.onerror = () => reject(new Error("Failed to load the Fluz widget script"));
      document.head.appendChild(script);
    });
  }
</script>

Una vez que el script haya cargado, llama a init() con tu clave de API, los detalles de la transacción y el patToken desde tu servidor.

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({
    apiKey: "",           // Your api_key
    patToken: "",         // The patToken generated on your server
    transaction_type: "", // e.g. DEPOSIT or WITHDRAW (see Init options)
    amount: 0.0,          // Amount in dollars and cents
    onOpen: () => console.log("Widget opened"),
    onClose: () => console.log("Widget closed"),
    onSuccess: (result) => console.log("Flow completed", result.externalReferenceId),
    onError: (error) => console.error(error.code, error.message),
  });
});

init() recibe transaction_type en snake case. La claim dentro del patToken firmado es transactionType. Ambas deben describir la misma transacción.

Elige cómo el usuario lanza el widget. Ambas opciones se ejecutan después de init().

Usar tu propio botón
Usar el botón de Fluz

Vincula open() a un botón que ya exista en tu página.

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({ /* options from step 2 */ });

  document
    .getElementById("existing-button") // replace with your selector
    ?.addEventListener("click", () => FluzEmbedded.open());
});

Agrega un botón de Fluz preetiquetado a un elemento de tu página. Al hacer clic llama a open().

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({ /* options from step 2 */ });

  const el = document.getElementById("btn-container"); // replace with your selector
  if (el) FluzEmbedded.renderButton(el);
});

Opciones de Init

Opción	Requerido	Qué hace
`apiKey`	Sí	El `api_key` de tu app, desde la pestaña Installation.
`patToken`	Sí	El token de transacción preaprobada firmado. Genéralo en tu servidor, nunca en JavaScript del navegador.
`transaction_type`	Sí	`DEPOSIT`, `WITHDRAW`, `CASH_DEPOSIT`, `PAY_IN`, `PAYOUT`, `KYB` o `ENROLLMENT`.
`amount`	La mayoría de los tipos	Un número. Omítelo para tipos que no llevan monto, como `KYB` y `ENROLLMENT`.
`container`	No	Solo en Staging. Un elemento o selector CSS. Cuando se establece, el widget se renderiza inline dentro de ese elemento en lugar de un modal a pantalla completa. Ver Renderizar inline.
`onOpen`	No	Se llama una vez que el widget ha sido agregado a la página.
`onClose`	No	Se llama cuando el widget es removido, ya sea por el usuario o por tu llamada a `close()`.
`onSuccess`	No	Se llama una sola vez cuando el flujo se completa y luego nunca más. Recibe los detalles de la sesión.
`onError`	No	Se llama cada vez que un intento falla: verificación de identidad, una transacción o el propio widget. Recibe `{ code, message }` más los detalles de sesión que se conozcan.

init() verifica solo lo que el script en sí necesita: apiKey, patToken, transaction_type y un container resoluble. Todo lo demás se valida contra tu token firmado, por lo que un transaction_type incorrecto o un amount faltante llega a ti a través de onError, no como un mensaje de consola que tu código no puede ver.

Métodos

Método	Qué hace
`FluzEmbedded.init(options)`	Configura el widget. Rechaza opciones inválidas y registra el motivo.
`FluzEmbedded.open()`	Renderiza el widget. `openModal()` es un alias mantenido para integraciones antiguas.
`FluzEmbedded.close()`	Elimina el widget y dispara `onClose`.
`FluzEmbedded.renderButton(element)`	Agrega un botón preetiquetado que llama a `open()` al hacer clic.
`FluzEmbedded.isOpen()`	Devuelve si el widget está renderizado actualmente.

Manejar el resultado

onOpen y onClose solo te indican que el widget apareció y desapareció, no si el usuario terminó. Para saber cómo terminó el flujo, pasa onSuccess y onError. Ambos son opcionales; si no pasas ninguno, el widget igual funciona, solo que no recibirás resultados.

FluzEmbedded.init({
  apiKey: "your-api-key",
  transaction_type: "PAY_IN",
  amount: 50.0,
  patToken: "your-token",
  onSuccess: ({ userId, accountId, externalReferenceId, email }) => {
    // UI only: show the user they're done and move them along.
    showConfirmation(externalReferenceId);
  },
  onError: ({ code, message, externalReferenceId }) => {
    if (code === "WIDGET-004") {
      // The token expired. Mint a fresh one and reopen.
      return refreshTokenAndReopen();
    }
    if (code === "US-0005" || code === "G-0004") {
      // The user is still in the widget and may retry.
      // Record the attempt; don't tear down your own flow.
      return recordFailedAttempt(code, externalReferenceId);
    }
    reportToSupport(code, message, externalReferenceId);
  },
});

No liquides desde onSuccess. Se ejecuta en el navegador del visitante, no lleva un registro verificable de la transacción y cualquiera puede llamarlo desde la consola. Úsalo para lo que ve el usuario: una confirmación, un redirect, quitar un spinner. Acredita cuentas, libera fulfillment o escribe en tu ledger solo desde tu servidor, activado por un webhook o una transacción que hayas obtenido y verificado tú mismo.

Cómo se comportan los callbacks

onSuccess es final. Se dispara como máximo una vez y no se entrega ningún resultado después de él, por lo que un flujo completado nunca también reporta un error.
onError reporta un intento, no un veredicto. Un usuario cuya verificación de identidad falla o cuyo pago es rechazado sigue en el widget y puede volver a intentar. onError puede dispararse más de una vez en una sesión, y un onSuccess posterior aún puede llegar.
Ninguno de los callbacks cierra el widget. El usuario permanece en pantalla hasta que lo cierre, lo cual dispara onClose.

Trata la sesión como terminada solo cuando se dispara onSuccess o el usuario cierra el widget.

Qué reciben los callbacks

Ambos callbacks incluyen, cuando se conozcan, los ids que vinculan la sesión con tus registros y los datos de contacto en la cuenta de Fluz que la ejecutó. Fluz los completa del lado del servidor a partir de tu token firmado y la sesión del usuario, por lo que son los valores que Fluz registró, no algo que la página haya armado.

Campo	De dónde proviene
`userId`	El id de usuario de Fluz (UUID). El mismo id que llevan los eventos de webhook, para que un resultado y un webhook posterior coincidan.
`accountId`	El id de cuenta de Fluz (UUID) contra la que corrió el flujo: la cuenta de consumidor del usuario, o su cuenta de negocio para un flujo empresarial.
`externalReferenceId`	El `externalId` que firmaste en el `patToken`, devuelto a ti.
`email`	El email de la cuenta de Fluz que ejecutó el flujo.
`phoneNumber`	El número de teléfono de esa cuenta, cuando haya uno registrado.

Lee cada campo por separado; no asumas que el conjunto está completo.

externalReferenceId proviene de tu token, por lo que sobrevive a fallas que ocurren antes de que un usuario inicie sesión.
Los otros cuatro provienen de la cuenta de Fluz y solo aparecen una vez que la sesión llegó hasta ese punto.
Una falla antes de que tu token se valide (un token expirado, un permiso de app faltante) no lleva nada. onError recibe solo code y message.

email y phoneNumber describen la cuenta de Fluz en la que el usuario inició sesión, que puede diferir de los valores que pasaste en el patToken. Estos campos identifican la sesión; no son un registro de lo que sucedió. Usa externalReferenceId para encontrar la fila correcta en tu sistema y luego confirma el resultado con un webhook o una llamada de API antes de actuar.

email y phoneNumber requieren un Origin registrado. Fluz dirige los mensajes de resultado al Origin en la pestaña OAuth de tu app e incluye datos de contacto solo cuando ese origin está configurado y utilizable. Sin un origin registrado, aún recibes los tres ids.Mantén el Origin apuntando a la página que integra el widget. Si nombra un host desde el que ya no integras, el navegador se niega a entregar los mensajes, por lo que onSuccess y onError dejan de dispararse. onOpen, onClose y el control de cierre no se ven afectados. El único rastro es una discrepancia de target-origin de postMessage en la consola del navegador. Consulta Configurar App Widget.

Códigos de error

onError recibe un code estable para ramificar y un message legible para registrar. US-0005 y G-0004 son intentos fallidos que el usuario puede reintentar; cualquier otro código significa que la sesión no puede continuar.

Código	Qué pasó	Qué hacer
`WIDGET-001`	Al link del widget le falta un parámetro requerido.	Revisa los valores que pasaste a `init()`. No reintentes.
`WIDGET-002`	El link del widget contiene un parámetro inválido.	Revisa `transaction_type` y `amount`. No reintentes.
`WIDGET-003`	A tu aplicación le faltan permisos que el widget necesita.	Contacta a tu account manager. No reintentes.
`WIDGET-004`	El token de la sesión ha expirado.	Genera un nuevo `patToken` y reabre el widget.
`WIDGET-005`	La sesión se terminó antes de completarse.	Inicia una nueva sesión.
`AUTH-0033`	La cuenta ya está vinculada a otro usuario de tu aplicación.	Dirige al usuario a la cuenta que ya conectó.
`US-0005`	El usuario no completó la verificación de identidad: la verificación falló sin paso posterior, o la cuenta está en revisión.	El usuario permanece en el widget y puede reintentar. No otorgues acceso que dependa de un usuario verificado.
`G-0004`	No se pudo completar la transacción.	El usuario permanece en la pantalla de confirmación y puede reintentar. No liquides ni liberes fondos.
`G-0001`	Algo salió mal de nuestro lado.	Reintenta una vez, luego alerta.

Trata cualquier código no reconocido como G-0001. Con el tiempo se lanzan nuevos códigos sin cambios disruptivos.

La opción container está disponible solo en staging. Las integraciones en producción deben usar el modal a pantalla completa predeterminado hasta que esté disponible allí.

De forma predeterminada, el widget monta una superposición fija de todo el viewport en tu página. Pasa un container y se renderiza dentro de un elemento que tú posicionas y dimensionas, sin overlay, bloqueo de scroll ni toma de control de la página.

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({
    apiKey: "",           // Your api_key
    patToken: "",         // The patToken generated on your server
    transaction_type: "WITHDRAW",
    amount: 50.0,
    container: "#fluz-widget", // a CSS selector or the element itself
    onClose: () => {
      // The container is now empty. Render what should replace the widget.
    },
  });

  FluzEmbedded.open();
});

Dimensionamiento

El widget llena tu contenedor al 100% de ancho y alto y nunca lo redimensiona. El contenido más alto que el contenedor hace scroll dentro del widget, no de tu página.

Configura un ancho y alto explícitos en el contenedor en tu CSS. Sin una altura, el widget recurre a la altura predeterminada de iframe del navegador de 150 px, el error más común en esta integración. El script registra una advertencia en la consola si el contenedor es demasiado pequeño cuando se abre el widget.
El tamaño mínimo compatible es 320 × 480 px. Todas las pantallas, incluyendo captura de documentos, 2FA y entrada de PIN, están soportadas en ese tamaño. Diseños más pequeños no están soportados.
No hay máximo. Los contenedores anchos obtienen el layout de escritorio, incluido el panel de resumen de la transacción; los estrechos obtienen el layout móvil.

Comportamiento	Modal	Inline
Overlay sobre tu página	Sí	No
Escape cierra el widget	Sí	No, tu página conserva la tecla
Se intercepta el botón atrás del navegador	Sí	No, tu página conserva su historial
Control de cierre del widget	Descarta el modal	Quita el widget y vacía tu contenedor

Planea para esa última fila: cuando el usuario cierra un widget inline, se dispara onClose y tu contenedor se vacía, así que renderiza su reemplazo desde onClose.

Errores del contenedor

Si el contenedor no puede usarse, no se renderiza nada, onOpen no se dispara y el script registra un error:

En init(): container no es ni un elemento ni un string no vacío. El widget queda sin configurar y un open() posterior se rechazará.
En open(): el selector no coincide con nada, no es CSS válido o el elemento no está adjunto al documento.

Un contenedor irresoluble nunca recurre al modal a pantalla completa.

Un selector de container se resuelve cuando se llama a open(), no en init(), por lo que está bien llamar a init() antes de que el elemento exista.

Crea una plataforma

Agregar el widget JS a tu página

1. Cargar el script del widget

2. Inicializar el widget

3. Abrir el widget

Opciones de Init

Métodos

Manejar el resultado

Cómo se comportan los callbacks

Qué reciben los callbacks

Códigos de error

Renderizar el widget inline (solo staging)

Dimensionamiento

Errores del contenedor

​1. Cargar el script del widget

​2. Inicializar el widget

​3. Abrir el widget

​Opciones de Init

​Métodos

​Manejar el resultado

​Cómo se comportan los callbacks

​Qué reciben los callbacks

​Códigos de error

​Renderizar el widget inline (solo staging)

​Dimensionamiento

​Diferencias con el modal

​Errores del contenedor

1. Cargar el script del widget

2. Inicializar el widget

3. Abrir el widget

Opciones de Init

Métodos

Manejar el resultado

Cómo se comportan los callbacks

Qué reciben los callbacks

Códigos de error

Renderizar el widget inline (solo staging)

Dimensionamiento

Diferencias con el modal

Errores del contenedor