Skip to main content

Quick start

This guide gets a basic Fluid cashier running on your site with correct session handling. It uses the main <fluid-widget> with Automatic Init, which suits most integrations. For the full option set see the Fluid Widget reference, and read Session handling before you go live.

Prerequisites​

  • Your operator-id, provided by Fluid Payments during onboarding. Payment methods and orchestrator configuration must also be provisioned for your operator before the cashier can show anything useful; if you are not sure this has happened, check before debugging your own code.
  • The authenticated user's session-id and user-id, plus their locale (IETF BCP 47, for example en-GB), country (ISO 3166-1 alpha-3, for example GBR) and currency (ISO 4217, for example GBP).
  • A page where you can add the Fluid script and the widget element after the user has logged in.

This guide covers the front end half of the integration. Your backend separately integrates with the payment orchestrator for session verification and transaction result notifications; see How Fluid Works.

note

Fluid does not operate the casino platform or the payment orchestrator test environments, so setting up a test environment is up to the operator, using your own staging platform and your orchestrator's test facilities. Contact Fluid Payments if you need more information.

1. Load the Fluid script after login​

Add the script to the page once the user is authenticated. Use a single, plain script tag:

<script src="https://get.fluidpayments.io/index.js"></script>

2. Add the widget with the real session details​

Inject <fluid-widget> with the required identity attributes, using the actual, current session-id of the authenticated user:

<fluid-widget
  operator-id="<your operator id>"
  user-id="<authenticated user id>"
  session-id="<authenticated user session id>"
  locale="en-GB"
  country="GBR"
  currency="GBP">
</fluid-widget>
warning

Passing an empty, placeholder, or changing session-id is the most common reason an integration fails. It must be the real session ID of the authenticated user, and it must stay stable for the session.

If your platform refreshes or rotates the session ID while the cashier is open, push the new value onto the session-id attribute. The attribute is observed even while the cashier is open, so the widget adopts the new session without being re-mounted. See Session handling.

Checkpoint: the element renders nothing visible yet (the cashier only shows once opened), but the script should have defined it. In the browser console, customElements.get('fluid-widget') returns a function and window.fluid is defined. If not, the script did not load; check the network tab and any content blockers.

3. Listen for events and wait until the widget is ready​

The widget reports its state through DOM events, and the one that matters most is initialised: the wallet must not be opened before it fires.

The sequence that guarantees you never miss it is:

  1. Load the Fluid script (step 1).
  2. Add the <fluid-widget> element with its required attributes (step 2). Initialisation starts as soon as the element is in the DOM.
  3. Attach the event listeners in the same synchronous script block, immediately after the element is in the DOM.

The element always defers its initialisation until after the current script block has finished, even when everything it needs is already cached and no network request happens, so the initialised event can never fire before your synchronously attached listeners are in place. What loses the event is attaching listeners late, for example after an await, inside a timeout, or in a framework lifecycle hook that runs after rendering has settled.

const fluid = document.querySelector('fluid-widget');

fluid.addEventListener('fluid-info', onInfo);
fluid.addEventListener('fluid-command', onCommand);
fluid.addEventListener('fluid-error', onError);

function onInfo(event) {
	if (event.detail.message === 'initialised') {
		// the widget is ready to be opened, e.g. enable your cashier button:
		depositButton.disabled = false;
		depositButton.addEventListener('click', () => {
			fluid.setAttribute('transaction', 'deposit');
			fluid.setAttribute('open', 'true');
		});
	}
}

function onCommand(event) {
	if (event.detail.message === 'close') {
		fluid.setAttribute('open', 'false');
	}
}

function onError(event) {
	console.error('Fluid error:', event.detail.message);
}

4. Open the wallet​

Once the widget is initialised, set open to true:

fluid.setAttribute('open', 'true');

Setting a transaction type is optional. When the attribute is absent the wallet defaults to deposit. Set it before opening if you want a different flow:

fluid.setAttribute('transaction', 'withdrawal'); // deposit (default) | withdrawal | quick-deposit
fluid.setAttribute('open', 'true');

When the user closes the wallet from inside, Fluid emits a close command. Set open back to false, as shown in step 3.

Checkpoint: the cashier opens as an overlay showing the payment methods configured for your operator. If it opens but shows no payment methods, your integration code is likely fine and the operator configuration is incomplete; contact Fluid Payments rather than debugging the embed.

5. Tear down on logout​

When the session ends, remove the element from the DOM so the widget shuts down cleanly:

document.querySelector('fluid-widget')?.remove();

Next steps​