Add the JS widget to your page

Before you begin: your server must generate a patToken for each session and make it available to your page. See Set up your server.

Add this loader to your page. It injects the widget script and resolves once FluzEmbedded is ready, so the rest of your code never runs before the widget exists.

<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.3.0";
      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>

Once the script has loaded, call init() with the transaction details and the patToken from your server.

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({
    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() takes transaction_type in snake case. The claim inside the signed patToken is transactionType. Both must describe the same transaction.

Do not pass apiKey to init(). Your API key is your application’s credential, and anything in your page is visible to the user. The script identifies your application from the signed patToken, which carries your appId. Versions before 1.3.0 required apiKey; 1.3.0 ignores it if it is still passed.

Choose how the user launches the widget. Both options run after init().

Use your own button
Use the Fluz button

Bind open() to a button that already exists on your page.

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

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

Append a pre-labeled Fluz button to an element on your page. Clicking it calls 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);
});

Init options

Option	Required	What it does
`patToken`	Yes	The signed pre-approved transaction token. Generate it on your server, never in browser JavaScript.
`transaction_type`	Yes	`DEPOSIT`, `WITHDRAW`, `CASH_DEPOSIT`, `PAY_IN`, `PAYOUT`, `KYB`, or `ENROLLMENT`.
`amount`	Most types	A number. Omit it for types that carry no amount, such as `KYB` and `ENROLLMENT`.
`container`	No	Staging only. An element or CSS selector. When set, the widget renders inline inside that element instead of in a fullscreen modal. See Render inline.
`onOpen`	No	Called once the widget has been added to the page.
`onClose`	No	Called when the widget is removed, whether by the user or by your call to `close()`.
`onSuccess`	No	Called once when the flow completes, then never again. Receives the session details.
`onError`	No	Called each time an attempt fails: identity verification, a transaction, or the widget itself. Receives `{ code, message }` plus whichever session details are known.

init() checks only what the script itself needs: patToken, transaction_type, and a resolvable container. Everything else is validated against your signed token, so a bad transaction_type or a missing amount reaches you through onError, not a console message your code can’t see.

Methods

Method	What it does
`FluzEmbedded.init(options)`	Configures the widget. Rejects invalid options and logs why.
`FluzEmbedded.open()`	Renders the widget. `openModal()` is an alias kept for older integrations.
`FluzEmbedded.close()`	Removes the widget and fires `onClose`.
`FluzEmbedded.renderButton(element)`	Appends a pre-labeled button that calls `open()` when clicked.
`FluzEmbedded.isOpen()`	Returns whether the widget is currently rendered.

Handle the outcome

onOpen and onClose only tell you the widget appeared and went away, not whether the user finished. To know how the flow ended, pass onSuccess and onError. Both are optional; if you pass neither, the widget still works, you just won’t receive outcomes.

FluzEmbedded.init({
  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);
  },
});

Do not settle from onSuccess. It runs in the visitor’s browser, carries no verifiable record of the transaction, and anyone can call it from the console. Use it for what the user sees: a confirmation, a redirect, clearing a spinner. Credit accounts, release fulfillment, or write to your ledger only from your server, driven by a webhook or a transaction you fetched and verified yourself.

How the callbacks behave

onSuccess is final. It fires at most once, and no outcome is delivered after it, so a completed flow never also reports an error.
onError reports an attempt, not a verdict. A user whose identity check fails or whose payment is declined is still in the widget and can try again. onError can fire more than once in a session, and a later onSuccess can still arrive.
Neither callback closes the widget. The user stays on screen until they dismiss it, which fires onClose.

Treat the session as over only when onSuccess fires or the user closes the widget.

What the callbacks receive

Both callbacks include, when known, the ids that tie the session to your records and the contact details on the Fluz account that ran it. Fluz fills these in server-side from your signed token and the user’s session, so they’re the values Fluz recorded, not anything the page assembled.

Field	Where it comes from
`userId`	The Fluz user id (UUID). The same id webhook events carry, so an outcome and a later webhook line up.
`accountId`	The Fluz account id (UUID) the flow ran against: the user’s consumer account, or their business account for a business flow.
`externalReferenceId`	The `externalId` you signed into the `patToken`, handed back to you.
`email`	The email on the Fluz account that ran the flow.
`phoneNumber`	The phone number on that account, when one is recorded.

Read each field on its own; don’t assume the set is complete.

externalReferenceId comes from your token, so it survives failures that happen before a user signs in.
The other four come from the Fluz account and only appear once the session got that far.
A failure before your token validates (an expired token, a missing app permission) carries nothing. onError receives only code and message.

email and phoneNumber describe the Fluz account the user signed into, which may differ from the values you passed in the patToken. These fields identify the session; they aren’t a record of what happened. Use externalReferenceId to find the right row in your system, then confirm the outcome with a webhook or API call before acting on it.

email and phoneNumber require a registered Origin. Fluz addresses outcome messages to the Origin on your app’s OAuth tab and includes contact details only when that origin is set and usable. With no origin on file, you still receive the three ids.Keep the Origin pointed at the page that embeds the widget. If it names a host you no longer embed from, the browser refuses to deliver the messages, so onSuccess and onError stop firing. onOpen, onClose, and the close control are unaffected. The only trace is a postMessage target-origin mismatch in the browser console. See Configure App Widget.

Error codes

onError receives a stable code to branch on and a human-readable message to log. US-0005 and G-0004 are failed attempts the user can retry; every other code means the session can’t continue.

Code	What happened	What to do
`WIDGET-001`	The widget link is missing a required parameter.	Check the values you passed to `init()`. Don’t retry.
`WIDGET-002`	The widget link contains an invalid parameter.	Check `transaction_type` and `amount`. Don’t retry.
`WIDGET-003`	Your application is missing permissions the widget needs.	Contact your account manager. Don’t retry.
`WIDGET-004`	The session token has expired.	Mint a new `patToken` and reopen the widget.
`WIDGET-005`	The session was terminated before it completed.	Start a new session.
`AUTH-0033`	The account is already linked to another user of your application.	Route the user to the account they already connected.
`US-0005`	The user didn’t complete identity verification: the check failed with no further step, or the account is in review.	The user stays in the widget and may retry. Don’t grant access that depends on a verified user.
`G-0004`	The transaction couldn’t be completed.	The user stays on the confirmation screen and may retry. Don’t settle or release funds.
`G-0001`	Something went wrong on our side.	Retry once, then alert.

Treat any unrecognized code like G-0001. New codes ship over time without a breaking change.

The container option is available on staging only. Production integrations must use the default fullscreen modal until it ships there.

By default, the widget mounts a fixed, full-viewport overlay on your page. Pass a container and it renders inside an element you position and size yourself, with no overlay, scroll lock, or page takeover.

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({
    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();
});

Sizing

The widget fills your container at 100% width and height and never resizes it. Content taller than the container scrolls inside the widget, not your page.

Set an explicit width and height on the container in your CSS. Without a height, the widget falls back to the browser’s default iframe height of 150px, the most common mistake in this integration. The script logs a console warning if the container is too small when the widget opens.
Minimum supported size is 320 × 480 px. Every screen, including document capture, 2FA, and PIN entry, is supported at that size. Smaller layouts aren’t supported.
There’s no maximum. Wide containers get the desktop layout, including the transaction summary pane; narrow ones get the mobile layout.

Behavior	Modal	Inline
Overlay on top of your page	Yes	No
Escape closes the widget	Yes	No, your page keeps the key
Browser back button is intercepted	Yes	No, your page keeps its history
Widget’s own close control	Dismisses the modal	Removes the widget and empties your container

Plan for that last row: when the user closes an inline widget, onClose fires and your container is emptied, so render its replacement from onClose.

Container errors

If the container can’t be used, nothing renders, onOpen doesn’t fire, and the script logs an error:

At init(): container is neither an element nor a non-empty string. The widget stays unconfigured, and a later open() refuses.
At open(): the selector matches nothing, isn’t valid CSS, or the element isn’t attached to the document.

An unresolvable container never falls back to the fullscreen modal.

A container selector is resolved when open() is called, not at init(), so it’s fine to call init() before the element exists.

Build a platform

Add the JS widget to your page

1. Load the widget script

2. Initialize the widget

3. Open the widget

Init options

Methods

Handle the outcome

How the callbacks behave

What the callbacks receive

Error codes

Render the widget inline (staging only)

Sizing

Container errors

​1. Load the widget script

​2. Initialize the widget

​3. Open the widget

​Init options

​Methods

​Handle the outcome

​How the callbacks behave

​What the callbacks receive

​Error codes

​Render the widget inline (staging only)

​Sizing

​Differences from the modal

​Container errors

1. Load the widget script

2. Initialize the widget

3. Open the widget

Init options

Methods

Handle the outcome

How the callbacks behave

What the callbacks receive

Error codes

Render the widget inline (staging only)

Sizing

Differences from the modal

Container errors