Common pitfalls
The mistakes on this page account for most of the support requests we receive during integrations. Each entry lists the symptom you will observe, the likely cause and the fix. If your integration misbehaves, scan this page first.
Session
Session handling is the most common source of first integration problems. The rules behind these fixes are explained on the Session handling page.
| Symptom | Likely cause | Fix |
|---|---|---|
Wallet never becomes ready, initialisation-failure fires | session-id is empty, a placeholder, or not a real session ID | Pass the real, current session ID of the authenticated user |
| Widget re-initialises constantly, or the screen flickers | session-id changes on every render, or the element is recreated on every render or route change | Use a stable value, mount and initialise once, and only change session-id on a genuine session rotation |
| Transactions fail after the platform session was refreshed | The new session ID was never pushed onto the widget | Update the session-id attribute whenever your platform rotates the session; it is observed even while the cashier is open |
| Widget still shows the previous user after an account switch | An identity attribute (user-id, operator-id, locale, country, currency) was changed on a live element; these are read once at mount, so the change does nothing | Remove the element and mount a fresh one with the new values. See Session handling |
| Previous user still shown after logout | The element was not removed at session end | Remove <fluid-widget> from the DOM on logout |
| "Where is the session expired event?" | There is no such event, refresh is automatic | Do not wait for one, and handle initialisation-failure for genuine failures only |
| Works in the first tab, broken in a second tab | The session is per tab | Make sure initialisation runs in every tab |
Script loading and initialisation
| Symptom | Likely cause | Fix |
|---|---|---|
| The widget does not render at all, no events fire | The Fluid script never loaded (blocked by a content blocker or CSP, or the tag was never added), so the custom element is not defined | Check the network tab for the script request; verify customElements.get('fluid-widget') returns a function and window.fluid is defined |
| The cashier opens but shows no payment methods | The operator configuration is incomplete, e.g. payment methods or orchestrator configuration not yet provisioned | Not an embed problem; contact Fluid Payments to complete the operator setup |
"Nothing happens when I call fluid.init()" | fluid.init() prepares the widget but does not open the UI | After initialised, set open="true" on the element |
| Wallet opens blank or errors | Opened before the initialised event | Wait for initialised, then open. See the sequence in the Quick start |
initialised event never observed, although the widget works | Listeners attached too late, after an await, a timeout, or a late framework lifecycle hook | Attach listeners in the same synchronous script block that adds the element |
window.fluid.bridge is undefined | Bridge handlers registered before the script finished loading | Register handlers inside the script.onload callback. See the Window Bridge API |
| Widget behaves erratically or duplicates events | More than one Fluid element mounted, or the script loaded twice | Keep exactly one element in the DOM and guard the script injection, as shown in Framework integrations |
A fluid.init() call rejects with Function call is throttled. Please wait. | fluid.init() is throttled to roughly once every two seconds; a call made too soon rejects its promise with that error | Call it once per session, right after loading the script |
Attributes and data
| Symptom | Likely cause | Fix |
|---|---|---|
invalid-user-data, invalid-bonus-data or invalid-transaction-attributes errors | An object was passed directly instead of stringified JSON | Pass object valued attributes through JSON.stringify(...). See Data objects |
| Widget renders in English despite another locale | The locale is not a valid IETF BCP 47 tag, so the widget fell back to en | Use a valid tag such as en-GB or es-MX; an invalid-init-attributes error accompanies the fallback |
fluid.init() rejects or types do not match | fluid.init() uses countryCode and currencyCode, while the HTML attributes are country and currency | Use the field names of the surface you are on. See Attributes |
| Wallet opens the wrong flow | transaction was never set; it defaults to deposit | Set transaction before opening if you want withdrawal or quick-deposit |
When an error event fires, its exact meaning is listed in the Events and errors catalogue.