Skip to content
FluidFluidDocs

Quick Start

This guide gets a basic Fluid cashier running on your site. You need three things before you begin:

  • An operator ID from Fluid Payments, provided 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 with Fluid before debugging your own code.
  • An authenticated user with a session ID and user ID
  • The user’s locale (IETF BCP 47, for example en-GB), country (ISO 3166-1 alpha-3, for example GBR) and currency (ISO 4217, for example GBP)

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

Step 1 — Load the Fluid script

Section titled “Step 1 — Load the Fluid script”

Add the script tag after your user has authenticated:

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

Checkpoint: 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.

Step 2 — Create the widget and listen for events

Section titled “Step 2 — Create the widget and listen for events”

Create the <fluid-widget> element, set the required identity attributes, and attach your event listeners before adding it to the page:

// 1. Create the element and set the identity attributes
const widget = document.createElement('fluid-widget');
widget.setAttribute('operator-id', 'your-operator-id');
widget.setAttribute('session-id', 'user-session-id');
widget.setAttribute('user-id', 'user-id');
widget.setAttribute('locale', 'en');
widget.setAttribute('currency', 'EUR');
widget.setAttribute('country', 'MLT');


// 2. Attach listeners BEFORE adding to the DOM
//    (#deposit-button is your own button that opens the cashier, initially disabled)
const depositButton = document.querySelector('#deposit-button');


widget.addEventListener('fluid-info', (e) => {
  console.log('Info:', e.detail);
  if (e.detail.message === 'initialised') {
    // Widget is ready: enable the button that opens it (Step 3)
    depositButton.disabled = false;
  }
});


widget.addEventListener('fluid-error', (e) => {
  console.error('Error:', e.detail);
});


widget.addEventListener('fluid-command', (e) => {
  if (e.detail.message === 'close') {
    // The user closed the cashier from inside it
    widget.setAttribute('open', 'false');
  }
});


// 3. Add to the page — initialisation starts automatically
document.body.appendChild(widget);

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.

Step 3 — Open the wallet

Section titled “Step 3 — Open the wallet”

Open the cashier from a user action, such as a Deposit button that you enable once the initialised event fires:

depositButton.addEventListener('click', () => {
  widget.setAttribute('open', 'true');
});

When the user closes the cashier from inside it, Fluid emits a close command; the listener in Step 2 sets open back to false.

The transaction attribute is optional; when it is absent the cashier opens on deposit. To open on a different transaction type, set it before opening:

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

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: check the operator’s payment methods in the Back Office, and if they look right, contact Fluid Payments rather than debugging the embed.

Step 4 — Clean up on logout

Section titled “Step 4 — Clean up on logout”

Remove the widget element from the DOM when the user’s session ends:

widget.remove();

What’s next

Section titled “What’s next”