# Fluid Docs — full documentation

> Source: https://docs.fluidpayments.io
> This file concatenates the body of every page in the Fluid public documentation.
> Generated by scripts/generate-llms.mjs — do not edit by hand.

---

# Introduction

> Source: https://docs.fluidpayments.io/docs/integration-manual/intro

This document gives an outline of the Fluid Wallet widgets and how they are integrated into the host website.

## 1. Fluid Widget
The main Fluid Widget has three principal user functions: **Deposit**, **Quick Deposit** and **Withdrawal**.
The initial screen presented to the user for each of these functions is shown in the figure below. These principal
functions allow the user to perform deposits and withdrawals with a variety of customised settings.
See how to integrate it [here](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration).

![](https://docs.fluidpayments.io/img/integration-manual/intro/principal-user-functions.png)

## 2. Fluid Quick Deposit
The Fluid Quick Deposit widget is a simplified version of the Fluid Wallet that allows the user to make a deposit with a single click, using their recently stored method.
If the user has no stored methods, the widget emits a notification to the host website, which it can react to by opening the Fluid Wallet for regular deposit.
This web component is designed with desktop gameplay in mind, and it is integrated into the DOM as an inline element, respecting its parent element styles.
See how to integrate it [here](https://docs.fluidpayments.io/docs/integration-manual/fluid-quick-deposit-integration).

![](https://docs.fluidpayments.io/img/integration-manual/intro/inline-quick-deposit.png)

## 3. Fluid Virtual for Sweepstakes

      The Fluid Virtual widget is a version of the Fluid Wallet
      that allows users to deposit and withdraw virtual currency for sweepstakes
      gameplay.

      It operates similarly to the main Fluid Wallet but is tailored for virtual
      currency transactions.
      See how to integrate it
      [here](https://docs.fluidpayments.io/docs/integration-manual/fluid-virtual-integration).

    **Packs selection**

      Fluid presents available sweepstakes packs to users organised in multiple sections:

- Promoted Packs as a carousel

- Special Promotion Pack as in its own banner

- Regular Packs as a grid

        Fluid also allows for purchasing custom amounts of virtual currency via the amount input field, with immediate conversion presented.

    **Visual features**

        Pack items can be styled with a predefined variant to highlight specific offers, and operators can configure which sections to display based on their promotional strategies;

- "regular" (default)

- "green"

- "red"

- "yellow"

- "promotion"

        The previous variant names ("best_value", "discount", "exclusive") are still accepted for backwards compatibility — see the [Sweepstakes integration page](https://docs.fluidpayments.io/docs/integration-manual/fluid-virtual-integration#backwards-compatibility) for details.
        Packs can also be tagged with a "Hot" label to draw user attention.

---

# Integration Tutorial

> Source: https://docs.fluidpayments.io/docs/integration-manual/tutorial

This page is an interactive component. View it in the browser at https://docs.fluidpayments.io/docs/integration-manual/tutorial.

---

# Fluid Virtual Widget Integration for Sweepstakes

> Source: https://docs.fluidpayments.io/docs/integration-manual/fluid-virtual-integration

The Fluid Virtual, same as the standard Fluid Widget, is implemented as a web component integrated into the
host page DOM. By design, the Fluid widget [script](https://get.fluidpayments.io/index.js) should get injected into the host
site **upon user authentication**, followed by injecting `<fluid-virtual>` web component into the DOM, providing required init attributes.

### Automatic Init

The `<fluid-virtual>` custom element expects several attributes required for initialisation (more on attributes [here](#fluid-virtual-custom-element-attributes-in-detail)). If the required initialisation parameters are provided at injection, the widget will automatically initialise and be ready for use. This initialisation should occur once per user session, immediately after user authentication. A [notification](#notifications-emitted-by-the-fluid-wallet) will indicate that the widget is ready for opening - it **should not be allowed to open before this notification is emitted**.

Once the session ends, the widget should be removed from the DOM to ensure proper shutdown.

## Fluid Virtual custom element attributes in detail

Fluid widget setup expects a list of parameters to properly configure itself for an authenticated user:

- `operator-id` - unique identifier of the host site / operator \*\*
- `session-id` - up-to-date session code of the currently authenticated user \*\*
- `user-id` - identifier of currently authenticated user \*\*
- `user-data` - details of currently authenticated user of type `FluidUserData` \*\*
- `locale` - locale tag according to IETF BCP 47 (e.g. `en-NZ` or `es-MX`), with `en` (default English) and `ar` (default Arabic) being an exception \*\*. POSIX-style underscores are normalised automatically (`en_GB` is accepted as `en-GB`). If the value is still invalid after normalisation, the widget falls back to `en` and emits a `fluid-error` event with message `invalid-init-attributes`.
- `country` - country of currently authenticated user in ISO 3166-1 Alpha-3 format \*\*
- `currency` - FIAT currency code according to ISO 4217 \*\*
- `virtual-currencies` - virtual currencies held by the user, object of type _VirtualCurrencies_ available in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package, stringified as JSON:

```ts
type VirtualCurrencies = {
    depositCurrency: VirtualCurrency;
    withdrawalCurrency: VirtualCurrency;
};

type VirtualCurrency = {
    name: string;
    code: string;
    symbol: string;
    exchangeRateToFiatCurrency: number;
    icon?: string;
    conversionOffset?: number;
};
```

- `transaction` - _deposit_ | _withdrawal_ | _quick-deposit_
- `lock-transaction-type` - When true, the user cannot switch from the current transaction type.
- `open` - _true_ or _false_
- `balance` - current user balances, object of type _VirtualBalance_ available in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package, stringified as JSON:

```ts
type VirtualBalance = {
    depositCurrencyBalance: number;
    withdrawalCurrencyBalance: number;
    lockedWithdrawalCurrencyBalance?: number;
};
```

- `packs` - stringified packs data, structure described [below](#packs-data-object)
- `deposit-limit` - responsible gaming deposit limit
- `success-cta-link` - link for the CTA button after a successful transaction
- `z-index` - use a value high enough to display the wallet in front of other elements on the host site
- `turned-over-percentage` - percentage of the turned over amount. If none is provided the information will not be displayed
- `transaction-attributes` - a stringified json object of key-value pairs that will be sent to the payment provider as transaction attributes together with the user agent and bonus code (if applicable)
- `deposit-amount` - the amount that will be pre-filled for the user in deposit. It takes precedence over the configured ones and should be unset for bringing back the default behaviour

\*\* Mandatory for Automatic Init

The `operator-id` value must correspond to the Payment Operator Config property value. This value is provided by Fluid Payments.

### Observed (reactive) Attributes

The following attributes are observed by the widget and change in their value on the host site causes a reaction/event within the wallet.

- `open` - triggers the wallet to become visible or hidden
- `balance` - up-to-date balance information in virtual currencies
- `session-id` - assures consistently valid user session

Other reactive attributes are observed only while the wallet is closed:

- `transaction` - updates transaction type
- `lock-transaction-type` - locks the transaction type, preventing the user from switching between Quick Buy and Redeem
- `deposit-limit` - updates responsible gaming deposit limit amount
- `user-data` - updates user data for resolving Suggested Deposit Amounts, Payment Methods Order and KYC status
- `success-cta-link` - sets the link to follow on successful transaction
- `turned-over-percentage` - sets the turned over percentage
- `transaction-attributes` - updates transaction attributes sent with each transaction request

Note that there won't be any reaction to changes of those 6 attributes while the wallet is open. This is to assure integrity of user's experience and that the transaction flow is not interrupted by any changes on the host site.

## Notifications emitted by the Fluid Wallet

In addition to receiving information from the host site, the Fluid wallet emits information out to the host website using `CustomEvent` (https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent),
with the `detail` property containing the information. This property is an object with the following structure, also available as a type in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package as `FluidNotificationDetail`

```ts
type FluidNotificationDetail = {
    message: string;
    [key: string]: any;
};
```

`message` contains a string with the different event types listed below.

Add the following code to receive those events:

```ts
fluid.addEventListener("fluid-command", onFluidCommand);
fluid.addEventListener("fluid-info", onFluidInfo);
fluid.addEventListener("fluid-error", onFluidError);
```

- `fluid-info` - messages of informational nature, with the purpose of e.g. tracking or allowing user action
- `fluid-error` - unexpected failure notifications
- `fluid-command` - commands to react to

Possible values of those types can be expected to be:

- `fluid-info`:
    - _initialised_ - wallet has been prepared for opening - it should not be allowed to open before this is emitted
    - _opened_ - the wallet has been opened
    - _destroyed_ - the wallet instance has been terminated
    - _internal-operation-change_ - transaction flow has been amended internally, e.g. upon withdrawal without a
      positive withdrawable balance
    - _success-cta-click_ - user clicked on the CTA shown on the transaction success screen
    - _deposit-success_ - when a successful deposit is made
    - _deposit-failure_ - deposit attempt failed
    - _error-cta-clicked_ - user clicked on the CTA shown on the transaction failure screen
    - _withdrawal-success_ - when a successful withdrawal is made
    - _withdrawal-failure_ - withdrawal attempt failed
    - _withdrawal-cancelled_ - when a withdrawal is cancelled
    - _contact-support_ - user clicked on the Contact Support link shown on transaction failure screen
    - _bonus-changed_ - user changed selected deposit bonus
    - _payment-method-changed_ - user changed the selected payment method
    - _dialog-opened_ - a dialog has been opened from the wallet
    - _dialog-closed_ - a dialog has been closed from the wallet
- `fluid-error`:
    - _initialisation-failure_ - Fluid wasn’t able to configure itself, e.g. due to a network or backend issue
    - _operation-execution-failure_ - an operation failed unexpectedly due to an error
    - _invalid-bonus-data_ - the bonus data is not in the correct format expected
    - _invalid-user-data_ - the user data is not in the correct format expected
    - _invalid-transaction-attributes_ - the transaction attributes are not in the correct format expected
    - _invalid-init-attributes_ - an init attribute (currently the `locale`) failed validation; the widget falls back to a safe default (`en` for `locale`) and keeps initialising.
- `fluid-command`:
    - _close_ - user selected to close the wallet from within, the `open` attribute should be set to _false_
    - _handle-transaction_ - when deposit or withdrawal is to be handled outside of Fluid
    - _start-kyc-verification_ - when the user clicks on the Verify button in the fluent message
    - _handle-banner-cta-click_ - when the user clicks on the banner on the first step of Quick Buy flow

Note that `fluid-info`notifications are not primarily designed for tracking, although some carry detailed information on the event, e.g. `payment-method-changed`, `bonus-changed` and all transaction result ones include `activityId`, representing unique user interaction with the wallet, which allows for stitching those events with a particular transaction id.

For cases where the widget needs to request data or trigger an action on the host page and receive a typed response, see the [Window Bridge API](https://docs.fluidpayments.io/docs/integration-manual/bridge-api).

## Example code

The following is an example of what's to be injected to your website DOM upon user login for Automatic Init:

```html
<script src="https://get.fluidpayments.io/index.js"></script>
<fluid-virtual
    operator-id="<your operator ID>"
    session-id="<authenticated user session ID>"
    user-id="<authenticated user ID>"
    user-data="<authenticated user details>"
    locale="<locale tag>"
    country="<authenticated user country>"
    currency="<user currency code>"
    transaction="<deposit / withdrawal / quick-deposit>"
    lock-transaction-type="<false / true>"
    open="<false / true>"
    balance="<user current balance>"
    packs="<packs data>"
    deposit-limit="<responsible gaming current deposit limit>"
    success-cta-link="<link to URL/Path following successful transaction>"
    z-index="<z-index value>"
    transaction-attributes="<stringified json object of key-value pairs for payment provider>"
    deposit-amount="<pre-filled deposit amount>"
    virtual-currencies="<virtual currency data>"
>
</fluid-virtual>
```

It should stay present in the DOM for the time of user session.

Initial mandatory attributes are: `operator-id`, `session-id`, `user-id`, `user-data`, `country`, `locale`, and `currency`.

## Packs Data Object

Fluid Virtual organises packs into five sections, each with its own layout: a grid of **regular** packs, a carousel of **promoted** packs (in the `green`, `red`, and `yellow` color variants), a **promoted special** banner, a **promoted on abort** modal, and a **promoted upsell** strip. The diagram below labels each pack type with the properties that drive its appearance — `label`, `price`, `previousPrice`, `discount`, `info`, `tagged`, and `expirationDate` — so you can map what you pass to what users see. The `variant` field only controls the badge **colour**; the badge text comes from `label`, the price-in-red treatment from `priceHighlighted`, and the upsell's secondary red badge from `discount`.

![Anatomy of a Sweepstakes pack](https://docs.fluidpayments.io/img/integration-manual/fluid-virtual-integration/sweepstakes-pack-structure.png)

_Figure - Anatomy of a Sweepstakes pack_

```ts
type Pack = {
    packId: string;
    variant: PackVariant;
    value: {
        price: number;
        previousPrice?: number;
        deposit: number;
        withdrawal: number;
    };
    logoUrl: string;
    logoAlt?: string;
    label?: string;
    title?: string; /** @deprecated Use `label` instead. */
    info?: string;
    tagged?: boolean;
    selected?: boolean;
    expirationDate?: Date;
    discount?: string;
    /**
     * When `true`, renders the current price in the accent (red) colour.
     * Has no visible effect when `value.previousPrice` is set — that path already uses the accent colour.
     * When omitted, treated as `false`.
     */
    priceHighlighted?: boolean;
};

type PackSet = {
    regular: Pack[];
    promoted: Pack[];
    promotedSpecial?: Pack;
    promotedUpsell?: Pack;
    promotedOnAbort?: Pack;
};
```

The structure containing sample data (type of _PackSet_ available in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package) is as follows:

```ts
const packs = {
    regular: [
        {
            packId: "pack-regular-01",
            logoUrl: "assets/images/sweepstakes/pack-4.99.png",
            variant: "regular",
            value: {
                price: 4.99,
                deposit: 5000,
                withdrawal: 5,
            },
        },
        {
            packId: "pack-regular-02",
            logoUrl: "assets/images/sweepstakes/pack-9.99.png",
            variant: "regular",
            value: {
                price: 9.99,
                deposit: 10000,
                withdrawal: 10,
            },
        },
    ],
    promoted: [
        {
            packId: "pack-red-01",
            logoUrl: "assets/images/sweepstakes/pack-red.png",
            variant: "red", // colour of the badge — purely visual
            label: "-25%", // text shown on the badge
            value: {
                price: 49.99,
                previousPrice: 64.99, // when set, the current price is auto-rendered in the accent (red) colour
                deposit: 65000,
                withdrawal: 65,
            },
        },
        {
            packId: "pack-yellow-01",
            logoUrl: "assets/images/sweepstakes/pack-yellow.png",
            variant: "yellow",
            label: "Exclusive",
            priceHighlighted: true, // renders the price in the accent (red) colour even without a previousPrice
            tagged: true,
            value: {
                price: 79.99,
                deposit: 100000,
                withdrawal: 100,
            },
        },
        {
            packId: "pack-green-01",
            logoUrl: "assets/images/sweepstakes/pack-green.png",
            variant: "green",
            label: "Best value",
            value: {
                price: 9.99,
                deposit: 15000,
                withdrawal: 15,
            },
        },
    ],
    promotedSpecial: {
        packId: "pack-promotion-01",
        logoUrl: "assets/images/sweepstakes/special-promotion.png",
        variant: "promotion",
        label: "Special promotion",
        info: "+ 5,000 purchases this week",
        expirationDate: "2026-12-31T23:59:59Z",
        value: {
            price: 74.99,
            previousPrice: 99.99, // previousPrice already paints the price in the accent colour — no priceHighlighted needed
            deposit: 10000,
            withdrawal: 5,
        },
    },
    promotedUpsell: {
        packId: "pack-promotion-upsell-01",
        logoUrl: "assets/images/sweepstakes/upsell-promotion.png",
        variant: "promotion",
        label: "Exclusive Offer",
        expirationDate: "2026-12-31T23:59:59Z",
        discount: "-15%", // the only place the `discount` field is rendered: as a second red badge next to `label`
        value: {
            price: 89.99,
            previousPrice: 99.99,
            deposit: 10000,
            withdrawal: 100,
        },
    },
    promotedOnAbort: {
        packId: "pack-promotion-upsell-modal-01",
        logoUrl: "assets/images/sweepstakes/upsell-promotion-modal.png",
        variant: "promotion",
        label: "Special promotion",
        info: "+ 5,000 purchases this week",
        expirationDate: "2026-12-31T23:59:59Z",
        value: {
            price: 89.99,
            previousPrice: 99.99,
            deposit: 10000,
            withdrawal: 100,
        },
    },
};
```

_Figure 4 - Definition of Packs Passed to the Fluid Widget (Example)_

### Packs usage

- **regular**: default list of packs, shown on _First-Time Deposit_ and in the _View All Packs_ dialog
- **promoted**: packs displayed in the carousel
- **promotedSpecial**: main promotional pack displayed below the carousel on _First-Time Deposit_ and in the _View All Packs_ dialog
- **promotedUpsell** pack displayed at the bottom of the payment method selection on _First-Time Deposit_ and on the first step of a _Subsequent Deposit_
- **promotedOnAbort** if available, displayed in a modal when the user closes the wallet during the deposit journey

### Packs structure

- `packId` (`string`) - unique identifier of the pack
- `variant` (`string`) - `'regular' | 'green' | 'red' | 'yellow' | 'promotion'`
- `value` (`object`) - details of the pack:
    - `price` (`number`) - price of the pack in FIAT currency
    - `previousPrice` (optional, `number`) - previous price of the pack in FIAT currency, used to show a price discount
    - `deposit` (`number`) - amount of virtual currency credited to user's deposit balance
    - `withdrawal` (`number`) - amount of virtual currency credited to user's withdrawal balance
- `logoUrl` (`string`) - URL of the pack image\*
- `logoAlt` (optional, `string`) - alt text for the pack image
- `label` (optional, `string`) - text shown on the pack badge (for example `"Best value"` on a `green` pack)
- `info` (optional, `string`) - additional info label for the pack
- `tagged` (optional, `boolean`) - indicates if the pack should be visually tagged
- `selected` (optional, `boolean`) - indicates if the pack is preselected
- `expirationDate` (optional, `Date`) - expiration date of the pack in ISO 8601 format
- `discount` (optional, `string`) - discount text, for example `"-25%"`. Used **only** by the promoted upsell, where it renders as a second red badge alongside `label`.
- `priceHighlighted` (optional, `boolean`) - renders the current price in the accent (red) colour. Has no visible effect when `value.previousPrice` is set (that path already uses the accent colour). Defaults to `false` when omitted.

### Backwards compatibility

The `label` property and the `green`/`red`/`yellow` variant values replace the previous `title` property and `best_value`/`discount`/`exclusive` variants. Existing integrations that still pass the deprecated names continue to work — Fluid normalizes them at the input boundary — but new integrations should use the new vocabulary, and existing operators are encouraged to migrate.

The normalization layer also preserves two side-effects the deprecated variants used to imply:

- Packs sent with `variant: "exclusive"` automatically get `priceHighlighted: true` so the price keeps rendering in the accent colour, matching the old yellow-exclusive look.
- Packs sent with `variant: "discount"` that only carry a `discount` text (and no `label`) automatically receive `label = discount` so the carousel badge keeps its text after the rendering switch from `discount` to `label`.

### Pack image dimensions

All the images used for the packs have **a ratio of 2:1**.
The available dimensions are:

- `regular`, `promoted` and `promotedUpsell` packs: 154px &times; 77px (308px &times; 154px for retina)
- `promotedSpecial` and `promotedOnAbort` packs: 328px &times; 164px (656px &times; 328px for retina)

The retina dimension is recommended, for a sharp display on mobile devices.

## User Data Object

Used for resolving Suggested Deposit Amounts and Payment Methods Order with use of Machine Learning based on historical transactions' data.

The structure, available as `FluidUserData` type in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package, is as follows:

```ts
type FluidUserData = {
    age?: number;
    affiliateId?: string;
    depositCount?: number;
    daysSinceRegistration?: number;
    fullName?: string;
    kycStatus?: FluidKycStatus;
    lifetimeDeposit?: number;
    previousDeposit?: number;
    tags?: string[];
};
```

All the properties are optional.

---

# Fluid Quick Deposit Integration

> Source: https://docs.fluidpayments.io/docs/integration-manual/fluid-quick-deposit-integration

## Overview

The **Fluid Quick Deposit** is a web component that integrates into the DOM similarly to the [Fluid Widget](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration).
It is designed as an inline element that respects its parent element styles and is intended for desktop gameplay.

## Integration

### Initialisation

Similar to the main Fluid Widget, `<fluid-quick-deposit>` component requires specific attributes to be initialised correctly. Please note that initialising one component will automatically prepare the other component for use, for improved performance.
[Programmatic initialisation](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#programmatic-init) can be used to initialise both components.

## Attributes

Compared to the Fluid Widget, the **Fluid Quick Deposit** component is simpler and requires only the following attributes:

- `operator-id` **
- `session-id`
- `user-id` **
- `locale` **
- `currency` **
- `country` **
- `z-index`
- `bonuses` ***
- `deposit-limit`
- `user-data`
- `transaction-attributes`
- `deposit-amount`

For detailed explanations of these attributes, refer to [Fluid custom element attributes in detail](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#fluid-custom-element-attributes-in-detail).

** Not required in case of [programmatic initialisation](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#programmatic-init).

*** Even if bonuses are not available during the quick deposit process, providing bonus data to the component serves performance purpose - bonuses will be processed just once and be available in the main Fluid Widget.

## Notifications

The **Fluid Quick Deposit** component emits the same event types as the [Fluid Widget](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#notifications-emitted-by-the-fluid-wallet) and introduces two additional events:

- `fluid-info`:
    - `deposit-cta-clicked` – Triggered when a user clicks the "Deposit" button (displayed when no recent payment method is available).
    - `error-cta-clicked` – Triggered when an error occurs in the deposit flow and the user clicks the "Try Again" button.

## Example Implementation

Below is an example of how to inject the **Fluid Quick Deposit** component into your website's DOM upon user login for automatic initialisation:

```html
<script src="https://get.fluidpayments.io/index.js"></script>
<fluid-quick-deposit
    operator-id="<your operator ID>"
    session-id="<authenticated user session ID>"
    user-id="<authenticated user ID>"
    user-data="<authenticated user details>"
    locale="<locale tag>"
    country="<authenticated user country>"
    currency="<user currency code>"
    bonuses="<bonus data>"
    deposit-limit="<responsible gaming current deposit limit>"
    z-index="<z-index value>"
    transaction-attributes="<stringified JSON object of key-value pairs for the payment provider>"
    deposit-amount="<pre-filled deposit amount>"
></fluid-quick-deposit>
```

For further details, refer to the documentation on [bonus data](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#bonus-data-object) and [user data](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#user-data-object) in the main widget [integration guide](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration).

---

# Fluid Widget Integration

> Source: https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration

## Integration

The Fluid Widget is implemented as a web component integrated into the
host page DOM. By design, the Fluid widget [script](https://get.fluidpayments.io/index.js) should get injected into the host
site **upon user authentication**, followed by either:

- injecting `<fluid-widget>` web component into the DOM, providing required init attributes (Automatic Init)
- calling `fluid.init` function with the init params object (Programmatic Init)

### Automatic Init

This is the recommended way in most cases.

The `<fluid-widget>` custom element expects several attributes required for initialisation (more on attributes [here](#fluid-custom-element-attributes-in-detail)). If the required initialisation parameters are provided at injection, the widget will automatically initialise and be ready for use. This initialisation should occur once per user session, immediately after user authentication. A [notification](#notifications-emitted-by-the-fluid-wallet) will indicate that the widget is ready for opening - it **should not be allowed to open before this notification is emitted**.

Once the session ends, the widget should be removed from the DOM to ensure proper shutdown.

### Programmatic Init

This method is recommended if the widget is embedded in an element rendered on open, injected many times.

If your website injects the Fluid component multiple times during a user session, ensure the widget is initialised upon user authentication. To do this, call the global `fluid.init` function with the necessary payload immediately after downloading the Fluid script. This function accepts an instance of the FluidInitParams type, available in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package. Unless it's specifically intended, `fluid.init` should be called only once per user session and to update widget parameters, use the [reactive attributes](#observed-reactive-attributes).

```ts
type FluidInitParams = {
    operatorId: number;
    userId: string;
    sessionId: string;
    locale: string;
    countryCode: string;
    currencyCode: string;
    bonuses?: FluidBonusData;
    userData?: FluidUserData;
    overscroll-behavior-auto?: boolean;
}
```

Then on injecting the widget component provide only the reactive parameters, like `transaction`, `open`, `balance`, `withdrawable-balance`, `bonuses`, `deposit-limit`, `success-cta-link` and `session-id`.

**Note:** if `bonuses` data doesn't change the widget won't process it again on inject, same with `session-id` - if it's the same as provided to the init function, the widget won't re-initialise. Otherwise, if any of the required init parameters change, the widget will re-initialise itself on inject.

**Validation:** `fluid.init` validates `locale` before initialising. POSIX-style underscores are normalised (`en_GB` is accepted as `en-GB`); if the resulting value is still not a valid IETF BCP 47 tag, the returned promise rejects with an `Error` whose `message` describes the offending value. This differs from the HTML-attribute path, which falls back to `en` and emits a `fluid-error` event instead — programmatic callers are expected to surface the failure explicitly.

**Warning:** Only one Fluid Widget custom element should be present in the DOM, otherwise unexpected behaviour may occur.

## Fluid custom element attributes in detail

Fluid widget setup expects a list of parameters to properly configure itself for an authenticated user:

- `operator-id` - unique identifier of the host site / operator \*\*
- `session-id` - up-to-date session code of the currently authenticated user \*\*
- `user-id` - identifier of currently authenticated user \*\*
- `user-data` - details of currently authenticated user of type `FluidUserData` \*\*
- `locale` - locale tag according to IETF BCP 47 (e.g. `en-NZ` or `es-MX`), with `en` (default English) and `ar` (default Arabic) being an exception \*\*. POSIX-style underscores are normalised automatically (`en_GB` is accepted as `en-GB`). If the value is still invalid after normalisation, the widget falls back to `en` and emits a `fluid-error` event with message `invalid-init-attributes`.
- `country` - country of currently authenticated user in ISO 3166-1 Alpha-3 format \*\*
- `currency` - currency code according to ISO 4217 \*\*
- `transaction` - _deposit_ | _withdrawal_ | _quick-deposit_
- `lock-transaction-type` - When true, the user cannot switch from the current transaction type.
- `open` - _true_ or _false_
- `balance` - current user balance in given currency
- `withdrawable-balance` - amount available to withdraw
- `bonuses` - stringified bonus data, structure described below
- `deposit-limit` - responsible gaming deposit limit
- `success-cta-link` - link for the CTA button after a successful transaction
- `z-index` - use a value high enough to display the wallet in front of other elements on the host site
- `turned-over-percentage` - percentage of the turned over amount. If none is provided the information will not be displayed
- `transaction-attributes` - a stringified JSON object of key-value pairs that will be sent to the payment provider as transaction attributes together with the user agent and bonus code (if applicable)
- `deposit-amount` - the amount that will be pre-filled for the user in deposit. It takes precedence over the configured ones and should be unset for bringing back the default behaviour
- `prefilled-bonus-code` - pre-fills the manual bonus code input field
- `two-factor-auth-enabled` - when `"true"`, adds a 2FA verification step to the withdrawal flow. See [verify2FA](https://docs.fluidpayments.io/docs/integration-manual/bridge-api#verify2fa)
- `overscroll-behavior-auto` - when added, the parameter will allow to set `overscroll-behavior` to `auto` for the [inline version](https://docs.fluidpayments.io/docs/backoffice-guide/settings/overview#embedded-within-as-inline-elements) of the cashier.
- `withdrawal-warning` - a stringified JSON object that displays a custom warning message on the withdrawal input screen, optionally with an action CTA. See [Withdrawal Warning](#withdrawal-warning) below for the object shape, examples and the emitted event.

\*\* Mandatory for Automatic Init

The `operator-id` value must correspond to the Payment Operator Config property value. This value is provided by Fluid Payments.

### Observed (reactive) Attributes

The following attributes are observed by the widget and change in their value on the host site causes a reaction/event within the wallet.

- `open` - triggers the wallet to become visible or hidden
- `balance` and `withdrawable-balance` - update withdrawal information
- `session-id` - assures consistently valid user session

Other reactive attributes are observed only while the wallet is closed:

- `transaction` - updates transaction type
- `lock-transaction-type` — locks the transaction type, preventing the user from switching between Deposit and Withdrawal
- `bonuses` - updates bonuses information
- `deposit-limit` - updates responsible gaming deposit limit amount
- `user-data` - updates user data for resolving Suggested Deposit Amounts, Payment Methods Order and KYC status
- `success-cta-link` - sets the link to follow on successful transaction
- `turned-over-percentage` - sets the turned over percentage
- `transaction-attributes` - updates transaction attributes sent with each transaction request
- `prefilled-bonus-code` - pre-fills the manual bonus code input field. Requires `manualBonusCodesEnabled` to be enabled in operator configuration. The code is not auto-validated; the user must click "Apply" to trigger verification via the [Bridge API](https://docs.fluidpayments.io/docs/integration-manual/bridge-api#verifybonuscode)
- `two-factor-auth-enabled` - when set to `"true"`, adds a 2FA verification step to the withdrawal flow. The user must enter a 6-digit authenticator code before the withdrawal is submitted. Code validation is handled via the [Bridge API](https://docs.fluidpayments.io/docs/integration-manual/bridge-api#verify2fa). This is a per-player flag — the host evaluates whether the player has 2FA enabled and sets it accordingly
- `withdrawal-warning` - updates the custom warning message displayed on the withdrawal input screen

Note that there won't be any reaction to changes of those attributes while the wallet is open. This is to assure integrity of user's experience and that the transaction flow is not interrupted by any changes on the host site.

## Notifications emitted by the Fluid Wallet

In addition to receiving information from the host site, the Fluid wallet emits information out to the host website using `CustomEvent` (https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent),
with the `detail` property containing the information. This property is an object with the following structure, also available as a type in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package as `FluidNotificationDetail`

```ts
type FluidNotificationDetail = {
	message: string;
	[key: string]: any;
};
```

`message` contains a string with the different event types listed below.

Add the following code to receive those events:

```ts
fluid.addEventListener("fluid-command", onFluidCommand);
fluid.addEventListener("fluid-info", onFluidInfo);
fluid.addEventListener("fluid-error", onFluidError);
```

- `fluid-info` - messages of informational nature, with the purpose of e.g. tracking or allowing user action
- `fluid-error` - unexpected failure notifications
- `fluid-command` - commands to react to

Possible values of those types can be expected to be:

- `fluid-info`:
    - _initialised_ - wallet has been prepared for opening - it should not be allowed to open before this is emitted
    - _opened_ - the wallet has been opened
    - _destroyed_ - the wallet instance has been terminated
    - _internal-operation-change_ - transaction flow has been amended internally, e.g. upon withdrawal without a
      positive withdrawable balance
    - _success-cta-click_ - user clicked on the CTA shown on the transaction success screen
    - _deposit-success_ - when a successful deposit is made
    - _deposit-failure_ - deposit attempt failed
    - _error-cta-clicked_ - user clicked on the CTA shown on the transaction failure screen
    - _withdrawal-success_ - when a successful withdrawal is made
    - _withdrawal-failure_ - withdrawal attempt failed
    - _withdrawal-cancelled_ - when a withdrawal is cancelled
    - _contact-support_ - user clicked on the Contact Support link shown on transaction failure screen
    - _bonus-changed_ - user changed selected deposit bonus
    - _payment-method-changed_ - user changed the selected payment method
    - _dialog-opened_ - a dialog has been opened from the wallet
    - _dialog-closed_ - a dialog has been closed from the wallet
- `fluid-error`:
    - _initialisation-failure_ - Fluid wasn’t able to configure itself, e.g. due to a network or backend issue
    - _operation-execution-failure_ - an operation failed unexpectedly due to an error
    - _invalid-bonus-data_ - the bonus data is not in the correct format expected
    - _invalid-user-data_ - the user data is not in the correct format expected
    - _invalid-transaction-attributes_ - the transaction attributes are not in the correct format expected
    - _invalid-init-attributes_ - an init attribute (currently the `locale`) failed validation; the widget falls back to a safe default (`en` for `locale`) and keeps initialising. When the widget is initialised programmatically via `fluid.init(...)`, the call rejects with an error instead (see [Programmatic Init](#programmatic-init) above).
    - _invalid-withdrawal-warning_ - the `withdrawal-warning` attribute could not be parsed as JSON. The widget renders no warning until the attribute is corrected. See [Withdrawal Warning](#withdrawal-warning).
- `fluid-command`:
    - _close_ - user selected to close the wallet from within, the `open` attribute should be set to _false_
    - _handle-transaction_ - when deposit or withdrawal is to be handled outside of Fluid
    - _start-kyc-verification_ - when the user clicks on the Verify button in the fluent message
    - _withdrawal-warning-cta-clicked_ - user clicked the CTA shown in the configured withdrawal warning. The host should react accordingly (for example, navigate the user to the bonuses screen). See [Withdrawal Warning](#withdrawal-warning).

Note that `fluid-info`notifications are not primarily designed for tracking, although some carry detailed information on the event, e.g. `payment-method-changed`, `bonus-changed` and all transaction result ones include `activityId`, representing unique user interaction with the wallet, which allows for stitching those events with a particular transaction id.

For cases where the widget needs to request data or trigger an action on the host page and receive a typed response, see the [Window Bridge API](https://docs.fluidpayments.io/docs/integration-manual/bridge-api).

## Example code

The following is an example of what's to be injected to your website DOM upon user login for Automatic Init:

```html
<script type="module" src="https://get.fluidpayments.io/index.js"></script>

<script src="https://get.fluidpayments.io/index.js"></script>
<fluid-widget
	operator-id="<your operator ID>"
	session-id="<authenticated user session ID>"
	user-id="<authenticated user ID>"
	user-data="<authenticated user details>"
	locale="<locale tag>"
	country="<authenticated user country>"
	currency="<user currency code>"
	transaction="<deposit / withdrawal / quick-deposit>"
	lock-transaction-type="<false / true>"
	open="<false / true>"
	balance="<user current balance>"
	withdrawable-balance="<user current withdrawable balance>"
	bonuses="<bonus data>"
	deposit-limit="<responsible gaming current deposit limit>"
	success-cta-link="<link to URL/Path following successful transaction>"
	z-index="<z-index value>"
	transaction-attributes="<stringified json object of key-value pairs for payment provider>"
	deposit-amount="<pre-filled deposit amount>"
	prefilled-bonus-code="<bonus code to pre-fill>"
	two-factor-auth-enabled="<false / true>"
>
</fluid-widget>
```

It should stay present in the DOM for the time of user session.

Initial mandatory attributes are: `operator-id`, `session-id`, `user-id`, `user-data`, `country`, and `locale`.

## Bonus Data Object

The structure containing sample data (type of `FluidBonusData` available in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package) is as follows:

```ts
const bonusData = [{
    "code": "DepositBonus",
    "title": "Deposit Bonus",
    "description": "100% up to 200€ + 10 Mega Spins",
    "logoUrl": "https://<operator-site>.com/assets/img/rewards/bonus-img/deposit-bonus.png",
    "maxBonus": 200,
    "maxBonusPercentage": 150,
    "minDeposit": 10,
    "maxDeposit": 250;
    "minDepositCount": 2;
    "maxDepositCount": 10;
    "minDaysSinceRegistration": 25;
    "maxDaysSinceRegistration": 180;
    "selected": true,
    "termsAndConditions": "Welcome Offer Terms And Conditions 1...",
    "paymentMethodFilter": {
        "applyTo": [
            {
                "providerType": "CREDITCARD"
            },
            {
                "providerType": "WEBREDIRECT",
                "service": "BLIXTPAY"
            }
        ],
        "excludeFrom": [
            {
                "providerType": "JETON"
            }
        ]
    }
}]
```

_Figure 4 - Definition of Bonuses Passed to the Fluid Widget (Example)_

- The `termsAndConditions` of the bonus should be provided as an HTML string.
- The `logoUrl` represents the URL of the bonus image\*. If `logoUrl` is absent or the path is 404, a fallback image will be used.
  This fallback image has to be set from the CMS's theme.
- Bonus codes will be available for all payment methods unless a `paymentMethodFilter` is specified.
- If a `paymentMethodFilter` is used, the bonus is applied depending on the properties set.
    - If `applyTo` is set then the bonus only would apply to those listed payment methods.
    - If `excludeFrom` is set then the bonus won’t apply to those payment methods.
- `providerType` is sufficient if the payment method does not have a `service`. Both values should be provided exactly as in Payment Provider configuration
- `maxBonus` and `maxBonusPercentage` are not mandatory.
- `maxBonusPercentage` requires a `maxBonus` value.
- `minDeposit` is an optional property indicating the minimum deposit amount required for the bonus.
- `maxDeposit` is an optional property indicating the maximum deposit amount required for the bonus.
- `minDaysSinceRegistration` is an optional property indicating the minimum days since player registration required for the bonus.
- `maxDaysSinceRegistration` is an optional property indicating the maximum days since player registration required for the bonus.
- If there is a `maxBonus` but no `maxBonusPercentage`, it is assumed that `maxBonusPercentage` is 100% (examples of bonus calculations can
  be found in [the deposit example section](https://docs.fluidpayments.io/docs/integration-manual/how-fluid-works#example-transaction-1-deposit)).
- `selected` is an optional property indicating the bonus should be preselected. If more than 1 bonus is set to true a bonus configuration error will be thrown.

\*Bonus logo image size should be 84x84px (168px168px for retina)

## User Data Object

Used for resolving Suggested Deposit Amounts and Payment Methods Order with use of Machine Learning based on historical transactions' data.

The structure, available as `FluidUserData` type in the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package, is as follows:

```ts
type FluidUserData = {
	age?: number;
	affiliateId?: string;
	depositCount?: number;
	daysSinceRegistration?: number;
	fullName?: string;
	kycStatus?: FluidKycStatus;
	lifetimeDeposit?: number;
	previousDeposit?: number;
	tags?: string[];
};
```

All the properties are optional.

## Withdrawal Warning

The `withdrawal-warning` attribute lets you surface a custom notice on the withdrawal input screen, for example, when an active bonus must be reviewed or cancelled before the player can withdraw. The warning appears in the initial (pre-focus) state of the amount input and is dismissed once the player focuses the input.

The attribute is observed while the wallet is closed: updating it then replaces the rendered warning the next time the wallet is opened.

The attribute value is a JSON string with the following shape:

```ts
type WithdrawalWarning = {
	title: string; // required, shown as the heading
	message?: string; // optional body text
	ctaLabel?: string; // optional; when set, renders a CTA button. Clicking emits `withdrawal-warning-cta-clicked` (fluid-command)
};
```

Field rules:

- `title` is required. If it is missing, the warning is silently not shown.
- `message` and `ctaLabel` are optional and independent. `ctaLabel` works with or without a `message`.
- When `ctaLabel` is set, a primary CTA button is rendered under the message. Clicking it emits a `fluid-command` event with `message: "withdrawal-warning-cta-clicked"`. Use this to react on the host page (for example, navigate the player to the bonuses screen).
- If the attribute value is not valid JSON, the widget emits an `invalid-withdrawal-warning` `fluid-error` event and renders no warning.

Minimal example — title and message only:

```html
<fluid-widget
	withdrawal-warning='{"title":"Active or Pending Bonuses","message":"You currently have an active/pending bonus. Please visit your profile and cancel the bonus to enable withdrawals."}'
	...
>
</fluid-widget>
```

With an action CTA:

```html
<fluid-widget
	withdrawal-warning='{"title":"Active or Pending Bonuses","message":"You currently have an active/pending bonus. Please visit your profile and cancel the bonus to enable withdrawals.","ctaLabel":"Review bonuses"}'
	...
>
</fluid-widget>
```

## Manual Bonus Codes

When the **Manual Bonus Codes** feature is enabled in the CMS (`Manual Bonus Codes Enabled`), the widget displays a text input allowing the user to enter a bonus code manually. The widget validates the code using the `verifyBonusCode` [Bridge API](https://docs.fluidpayments.io/docs/integration-manual/bridge-api) method.

### Enabling the feature

The feature is controlled by the `Manual Bonus Codes Enabled` setting in the Fluid CMS. When enabled, a bonus code input field appears in the deposit flow alongside the regular bonus list.

### Bridge handler

The host page must register a `verifyBonusCode` handler as described in the [Window Bridge API](https://docs.fluidpayments.io/docs/integration-manual/bridge-api) documentation. The handler receives `{ code: string }` (the trimmed user input) and must return a `FluidBridgeVerifyBonusCodeResponse`:

- When `status` is `'valid'`, the `bonus` object must conform to the same structure as entries in the [Bonus Data Object](#bonus-data-object) — including optional `paymentMethodFilter`, `logoUrl`, and `termsAndConditions`.
- When `status` is `'invalid'`, the widget displays an error message to the user.
- Optionally, return `autoOptedIn: true` on a valid response to control the post-validation bonus UX. See [`autoOptedIn` behaviour](https://docs.fluidpayments.io/docs/integration-manual/bridge-api#autooptedin-behaviour) for the full behaviour table.

## CSS

### Font

The `font-family` used by the widget will inherit from its parent element, ensuring consistency with the host site's typography.

If another font is desired, it can be set on the parent element of the `<fluid-widget>`.

The widget uses [three different font weights](https://docs.fluidpayments.io/docs/backoffice-guide/theme#font-weight), so the font-family should include all of them.

---

# Framework integrations

> Source: https://docs.fluidpayments.io/docs/integration-manual/framework-integrations

## React

While React is yet to improve their Web Component support in version
19 (https://github.com/facebook/react/issues/11347#issuecomment-1122275286) the current solution requires a simple workaround to assure
critical Widget parameters are set on init.

The Widget wrapper and `useEffect`:

```jsx
let scriptLoaded = false;

function FluidWrapper({ open, transaction, bonuses,  onInfo, onCommand, onError }) {
	const ref = useRef(null);

	useEffect(() => {
		let script;
		if (window && document && !scriptLoaded) {
			script = document.createElement('script');
			script.src = 'https://get.fluidpayments.io/index.js';
			script.onload = () => {
				console.log('Fluid script loaded');
			};
			document.head.appendChild(script);

			scriptLoaded = true;
		}

		return () => {
			if (script) {
				script.remove();
			}
		};
	}, []);

	useLayoutEffect(() => {
		const fluid = ref.current;

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

		return () => {
			fluid.removeEventListener('fluid-command', onCommand);
			fluid.removeEventListener('fluid-info', onInfo);
			fluid.removeEventListener('fluid-error', onError);
		}
	}, [onCommand, onError, onInfo, ref]);

	return (
		<fluid-widget
			ref={ref}
			id="fluid-widget"
			operator-id="10000001"
			user-id="10001"
			session-id=""
			locale="en"
			currency="EUR"
			user-data={ JSON.stringify(userData) }
			transaction={ transaction }
			open={ open }
			balance="1000"
			withdrawable-balance="900"
			bonuses={ JSON.stringify(bonuses || []) }
			deposit-limit=""
			success-cta-link="">
		</fluid-widget>
	);
}
```

Mind the `scriptLoaded` is there to prevent React from loading the Widget script twice on render.

An example of possible integration use:

```jsx
function App() {
	const [open, setOpen] = useState(false);
	const [transaction, setTransaction] = useState('deposit');
	const [numberOfBonuses, setNumberOfBonuses] = useState(bonuses.length);

	function deposit() {
		setTransaction('deposit');
		setOpen(true);
	}

	function withdraw() {
		setTransaction('withdrawal');
		setOpen(true);
	}

	function quickDeposit() {
		setTransaction('quick-deposit');
		setOpen(true);
	}

	function close() {
		setOpen(false);
	}

	function onCommand(event) {
		console.info(`%cFluid COMMAND: ${event.detail}`, 'color: lightgreen', event);

		if (event.detail === 'close') {
			close();
		}
	}

	function onInfo(event) {
		console.info(`%cFluid INFO: ${event.detail}`, 'color: cornflowerblue', event);
	}

	function onError(event) {
		console.error(`Fluid ERROR: ${event.detail}`, event);
	}

	function changeNumberOfBonuses() {
		const newNumberOfBonuses = numberOfBonuses - 1 < 0 ? 3 : numberOfBonuses - 1;
		setNumberOfBonuses(newNumberOfBonuses);
		console.log('Number of bonuses set to', newNumberOfBonuses);
	}

	return (
		<>
			<h1>
				<img src="/logo-mark-light.png" alt="Fluid" width={48} style={{ marginRight: '1rem' }} />
				Fluid
			</h1>

			<div style={{ marginBottom: '1rem' }}>
				<button onClick={ deposit }>Deposit
				</button>
			</div>
			<div style={{ marginBottom: '1rem' }}>
				<button onClick={ withdraw }>
					Withdrawal
				</button>
			</div>
			<div style={{ marginBottom: '1rem' }}>
				<button onClick={ quickDeposit }>
					Quick Deposit
				</button>
			</div>

			<div style={{ marginBottom: '1rem' }}>
				<button onClick={ changeNumberOfBonuses }>
					Change bonuses
				</button>
			</div>

			<FluidWrapper
				open={open}
				transaction={transaction}
				bonuses={bonuses.slice(0, numberOfBonuses)}
				onInfo={ onInfo }
				onCommand={ onCommand }
				onError={ onError }
			/>
		</>
	)
}
```

Complete code of the POC: https://github.com/soltechno/fluid-react-integration

---

# How Fluid Works

> Source: https://docs.fluidpayments.io/docs/integration-manual/how-fluid-works

## Example Transaction 1: Deposit

When depositing funds, the user may have payment methods stored (e.g. credit card, ewallet etc), along with the associated details stored.
This enables a user to choose one or their preferred payment methods and deposit funds seamlessly.

In addition to the previously stored payment methods, various other methods can be presented to the user should they wish to use a new
method (stored after using it for the first time). The wallet can customise the ordering of the stored and new payment methods. Each payment
method has its own minimum deposit and maximum deposit limits. Each method also has its own set of bonuses that can be used with the method.

The figure below gives an example of how the fluid-widget element may appear in the rendered html for a transaction deposit. Once the user
is authenticated on the host site, they are identified by the the user-id attribute. Data relating to the language used , currency, user
balance etc are passed in and determine the appearance of the wallet, as illustrated below. The various steps shown in this example are for
a user depositing **100€** using a credit card. Note the bonuses data is passed in as a stringified array of json bonus objects. This is
detailed in the following section “Bonuses”.

![Deposit user journey](https://docs.fluidpayments.io/img/integration-manual/how-fluid-works/deposit-user-journey.png)

_Figure 1 - Example User Journey for a Deposit_

The maxBonus property defines the maximum bonus amount that can be claimed. For example, in the image below showing the preselected bonus,
the maxBonus amount would be **150€**.

The maxBonusPercentage property defines the multiple applied to the amount deposited by the user to calculate the bonus amount added. This
multiple is expressed as a percentage. For example, if the maxBonusPercentage is **150%** and the user deposits **50€**, then the bonus
amount would be **75€** *(50 x 150% = 75).* As a second example, if the maxBonusPercentage is **100%** and the user deposits **200€,** the
bonus amount would be **200€** *(200 x 100% = 200).* In the image below, the maxBonusPercentage is **100%**, hence the text
***“100% up to 150€ + …”*** for the login bonus.

A specific bonus can be preselected by setting `"selected": true` on the corresponding entry in the `bonuses` array (see the [Bonus Data Object](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#bonus-data-object)). The preselected bonus must be part of the `bonuses` array passed to the widget. The `bonuses` attribute is observed, so the preselection can be changed after the wallet has loaded. Preselection is useful when the user is referred to the operator with a specific bonus offer, for example.

![Preselected bonus](https://docs.fluidpayments.io/img/integration-manual/how-fluid-works/preselected-bonus.png)

_Figure 2 - Example of a Preselected Bonus_

## Example Transaction 2: Quick Deposit

For quick deposits, the user can deposit funds with the least effort simply by entering say CVC
number and deposit amount. The figure below gives an example of how the fluid-widget element may appear in the rendered html for a quick
deposit. Note the transaction attribute value is “quick-deposit”. As before, the various attribute values determine the various settings of
the wallet, tailored to the user.

![Quick Deposit: Step 1](https://docs.fluidpayments.io/img/integration-manual/how-fluid-works/quick-deposit-step-1.png)

_Figure 3 - Quick Deposit: Step 1_

## Example Transaction 3: Withdrawal

The figure below shows the Fluid Wallet for a withdrawal transaction. Note in this example, the withdrawable balance of **900€** is passed
in as property and displayed in the initial screen presented to the user.

![Withdrawal: Step 1](https://docs.fluidpayments.io/img/integration-manual/how-fluid-works/withdrawal.png)

_Figure 4 - Withdrawal: Step 1_

## Responsible Gaming Limit

The wallet enables responsible gaming limits to be defined and when applicable, the max deposit amount is adjusted
amount on step 1. Each payment had its own maximum deposit amount, however when the responsible gaming is below this
limit, the maximum deposit is limited to this value. For example, in the figure below the responsible gaming limit
is set at **220€** (shown as Max: €220). If the user enters an amount exceeding this limit, the text is highlighted
red and the fluent box displays the limit set by responsible gaming.

![Responsible Gaming Limit](https://docs.fluidpayments.io/img/integration-manual/how-fluid-works/responsible-gaming-limit.png)

_Figure 5 - Responsible Gaming Limit_

---

# Integrating with AI

> Source: https://docs.fluidpayments.io/docs/integration-manual/integrating-with-ai

The Fluid public documentation is also available in an AI-friendly form following the [llmstxt.org](https://llmstxt.org) standard. AI coding assistants (Cursor, Claude, ChatGPT and others) can read these files directly to answer questions about embedding the Fluid Cashier or configuring it from the back office.

Two files are published:

- **Index** — [`https://docs.fluidpayments.io/llms.txt`](https://docs.fluidpayments.io/llms.txt) — a short list of every public page with a one-line summary and link.
- **Full text** — [`https://docs.fluidpayments.io/llms-full.txt`](https://docs.fluidpayments.io/llms-full.txt) — every public page concatenated into a single Markdown file.

## How to use them

- **In a chat assistant** — paste either URL into the conversation and ask your question. Most AI assistants will fetch and ingest the file.
- **In a developer tool** (e.g. Cursor, Claude Code, Codex) — add the URL as documentation context, or download `llms-full.txt` and reference it from your prompt.
- **In an automated pipeline** — fetch `llms.txt` to discover available pages, then fetch individual pages as needed.

## Caveat

AI answers are only as accurate as the documentation they are given, and Fluid's product evolves over time. Always verify integration steps against the live documentation and your operator-specific configuration before shipping.

---

# Operator Configuration

> Source: https://docs.fluidpayments.io/docs/integration-manual/operator-configuration

## Transaction Result Callbacks

The transaction result callback URLs are defined in DatoCMS, on the **Payment Gateway** model in the **Callback Urls** section. Set the Success, Pending, Cancel and Failure callback URL fields to the Fluid transaction result URL for each outcome (`state=SUCCESS`, `state=PENDING`, `state=CANCELLED`, `state=FAILED`). Fluid completes the per transaction values automatically, delivers each result back to the user and forwards it to your platform where required.

## Fluid Wallet Content defined by the Operator

Much of the content of the fluid wallet can be customised by the operator. Such content includes visual elements like the colour theme of
the wallet, the style of the buttons etc. Other content defined by the operator includes certain text that is displayed in the various pages
and modal boxes that are presented to the user. Currently, this is retrieved from a DatoCMS database. The image below shows examples of text
content displayed in the wallet, some of which are taken from the wallet in a dark colour theme.

![Text content customized](https://docs.fluidpayments.io/img/integration-manual/operator-configuration/fluid-content-defined-by-the-operator.png)

_Figure 1 - Example Text Content at various Steps in the Fluid Wallet_

## Fluid Wallet Behaviour Defined by the Operator

Following a successful transaction, the user is notified in the final step with the amount being deposited or withdrawn, as shown below. The
exact text displayed on the buttons (indicated 1,2,3) can be configured by the operator. The operator can also define what action is
performed when the user clicks on this button **Play now** e.g. the user may be taken to the home screen of the operator or simply have the wallet close
with the user returning to the screen from which the wallet was opened.

![Final Step Notification](https://docs.fluidpayments.io/img/integration-manual/operator-configuration/fluid-behaviour-defined-by-the-operator.png)

_Figure 2 - Example Final Step Notification_

In a similar manner to above, the buttons **Try again** and **Contact support** can be configured by the operator.

![Example Transaction Failure Cases](https://docs.fluidpayments.io/img/integration-manual/operator-configuration/errors.png)

_Figure 3 - Example Transaction Failure Cases_

## Fluid Wallet Content Defined by the Operator

### Theme

One of Fluid's strengths is the possibility of matching the wallet style with the host(casino).
The wallet can follow the new [casino theme](https://docs.fluidpayments.io/docs/backoffice-guide/theme) for a specific event, like Xmas.

### Content Set

The translations used by the wallet.
The copy could be selected to fit the theme. For example, the tone of voice of the fluent box could be different for Xmas.

---

# Window Bridge API

> Source: https://docs.fluidpayments.io/docs/integration-manual/bridge-api

The Window Bridge API provides a request/response communication channel between the Fluid widget and the host page. It complements the existing [one-way event model](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration#notifications-emitted-by-the-fluid-wallet) for cases where the widget needs to ask the host page for data and await a typed response.

## Events vs. Bridge

| Use case | Mechanism |
|---|---|
| Widget notifying the host that something happened | DOM `CustomEvent` (`fluid-info`, `fluid-command`, `fluid-error`) |
| Widget requesting data or an action from the host and awaiting a typed response | `window.fluid.bridge.handleRequest(...)` |

## How the method name connects both sides

The method name string is the shared key between the widget and your page. Your handler must be registered under **exactly the same name** that the widget uses when it calls that method. If the names do not match, the request rejects immediately with `BRIDGE_HANDLER_NOT_FOUND`.

## Registering a handler

The host page registers a handler by calling `window.fluid.bridge.handleRequest(methodName, handler)`. This should be done **before** the widget needs the data — typically right after the Fluid script is loaded.

Bridge handlers must be registered **after** the Fluid script has finished executing, otherwise `window.fluid.bridge` is `undefined`. See [Script loading for bridge usage](#script-loading-for-bridge-usage) below for both inline and programmatic loading patterns.

```ts
window.fluid.bridge.handleRequest('verifyBonusCode', async ({ code }) => {
    const result = await myApi.verifyBonusCode(code);
    if (!result.valid) {
        return { status: 'invalid' };
    }
    return { status: 'valid', bonus: result.bonus, autoOptedIn: result.autoOptedIn };
});
```

Calling `handleRequest` again with the same method name silently replaces the previous handler.

## Defining the typed contract

Bridge method names and their request/response shapes are defined by augmenting the `FluidBridgeContract` interface from the [`@fluidpayments/types`](https://www.npmjs.com/package/@fluidpayments/types) package in your host application.

`@fluidpayments/types` ships response types for each bridge method:

```ts
import type {
    FluidBridgeVerifyBonusCodeResponse,
    FluidBridgeVerify2FAResponse
} from '@fluidpayments/types';

declare module '@fluidpayments/types' {
    interface FluidBridgeContract {
        verifyBonusCode: {
            request: { code: string };
            response: FluidBridgeVerifyBonusCodeResponse;
        };
        verify2FA: {
            request: { code: string };
            response: FluidBridgeVerify2FAResponse;
        };
    }
}
```

This gives you compile-time safety: your handler signature will be typed according to the contract you define.

## Timeout and errors

All bridge requests have a fixed timeout of **5000ms**. If the handler does not respond within that time, or if no handler has been registered, the returned promise rejects with a `FluidBridgeError` object:

```ts
type FluidBridgeError = {
    code: 'BRIDGE_HANDLER_NOT_FOUND' | 'BRIDGE_TIMEOUT' | 'BRIDGE_HANDLER_ERROR';
    message: string;
    details?: unknown; // present for BRIDGE_HANDLER_ERROR — contains the original thrown value
};
```

| `code` | Cause |
|---|---|
| `BRIDGE_HANDLER_NOT_FOUND` | No handler has been registered for the requested method |
| `BRIDGE_TIMEOUT` | The handler did not resolve within 5000ms |
| `BRIDGE_HANDLER_ERROR` | The handler threw or returned a rejected promise |

## Available methods

List of bridge methods that the Fluid Widget may invoke. You only need to register handlers for the methods your integration uses.

### `verifyBonusCode`

Validates a manual bonus code entered by the user. The widget invokes this method when the user clicks "Apply" in the manual bonus code input.

**Required when** the `manualBonusCodesEnabled` operator configuration flag is enabled. If the flag is enabled but no handler is registered, the widget will show a validation error after the 5000ms timeout.

#### Request payload

```ts
{ code: string }
```

| Field | Type | Description |
|---|---|---|
| `code` | `string` | The bonus code the user entered (trimmed) |

#### Response payload

```ts
type FluidBridgeVerifyBonusCodeResponse = {
    status: 'valid' | 'invalid';
    bonus?: FluidBonusData;
    autoOptedIn?: boolean;
};
```

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `'valid'` \| `'invalid'` | Yes | Whether the code is valid |
| `bonus` | `FluidBonusData` | When `status` is `'valid'` | The bonus details to display |
| `autoOptedIn` | `boolean` | No | Controls whether the user is automatically opted into the bonus. Defaults to `false` when omitted |

The `bonus` object follows the same `FluidBonusData` shape used in the `bonuses` attribute:

```ts
{
    code: string;
    title: string;
    description: string;
    logoUrl?: string;
    termsAndConditions?: string;
    minDeposit?: number;
    maxDeposit?: number;
    maxBonus?: number;
    maxBonusPercentage?: number;
    paymentMethodFilter?: string[];
}
```

#### `autoOptedIn` behaviour

When `autoOptedIn` is `true`, the user is automatically opted into the validated bonus without needing to confirm via the bonus selection UI.

When `autoOptedIn` is `false` or absent, the user must confirm their bonus selection — for stored-methods users the bonus list modal auto-opens after validation.

| Flow | `autoOptedIn` | Behaviour |
|---|---|---|
| First-time depositor (no stored methods) | `false` / absent | Default — bonus shown on the bonus selection step; user confirms before proceeding |
| First-time depositor (no stored methods) | `true` | Bonus selector card shown on step 1, bonus step skipped |
| Stored methods | `true` | Default — works as before |
| Stored methods | `false` / absent | Bonus list modal auto-opens after validation |

#### Example

```ts
// Register the verifyBonusCode handler once after the Fluid script loads
window.fluid.bridge.handleRequest('verifyBonusCode', async ({ code }) => {
    const result = await myApi.verifyBonusCode(code);

    if (!result.valid) {
        return { status: 'invalid' };
    }

    return {
        status: 'valid',
        bonus: {
            code: result.code,
            title: result.title,
            description: result.description,
            logoUrl: result.logoUrl,
            termsAndConditions: result.termsAndConditions,
            minDeposit: result.minDeposit,
            maxBonus: result.maxBonus,
            maxBonusPercentage: result.maxBonusPercentage,
            paymentMethodFilter: result.paymentMethodFilter,
        },
        autoOptedIn: result.autoOptedIn,
    };
});
```

### `verify2FA`

Validates a 6-digit authenticator code entered by the user during the withdrawal flow. The widget invokes this method when the user clicks "Verify code" in the 2FA verification step.

**Required when** the `two-factor-auth-enabled` attribute is set to `"true"` on the widget element. If the attribute is enabled but no handler is registered, the widget will show a validation error after the 5000ms timeout.

#### Request payload

```ts
{ code: string }
```

| Field | Type | Description |
|---|---|---|
| `code` | `string` | The 6-digit authenticator code the user entered |

#### Response payload

```ts
type FluidBridgeVerify2FAResponse =
    | { status: 'valid' }
    | { status: 'invalid' }
    | { status: 'rate_limited'; retryAfterMs?: number };
```

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `'valid'` \| `'invalid'` \| `'rate_limited'` | Yes | The verification result |
| `retryAfterMs` | `number` | No | Milliseconds before the user can retry. Only used when `status` is `'rate_limited'`. The widget shows a countdown and auto-re-enables the input after this period. The `{seconds}` placeholder in the rate limit content key is interpolated from this value |

#### Example

```ts
// Register the verify2FA handler once after the Fluid script loads
window.fluid.bridge.handleRequest('verify2FA', async ({ code }) => {
    const result = await myApi.verify2FA(code);

    if (result.valid) {
        return { status: 'valid' };
    }

    if (result.rateLimited) {
        return { status: 'rate_limited', retryAfterMs: result.retryAfterMs };
    }

    return { status: 'invalid' };
});
```

## Script loading for bridge usage

Bridge handlers must be registered **after** the Fluid script has finished executing. There are two common loading patterns:

### Inline `<script>` tag

Use a plain `<script>` tag — **not** `type="module"`, `async`, or `defer` — so that `window.fluid.bridge` is available immediately in the next script block:

```html
<script src="https://get.fluidpayments.io/index.js"></script>
<script>
    // window.fluid.bridge is guaranteed to exist here
    window.fluid.bridge.handleRequest('verifyBonusCode', async ({ code }) => {
        // ...
    });
</script>
```

### Programmatic loading

When loading the script dynamically (common in SPA / framework integrations), register handlers in the `onload` callback:

```js
const script = document.createElement('script');
script.src = 'https://get.fluidpayments.io/index.js';
script.onload = () => {
    // window.fluid.bridge is guaranteed to exist here
    window.fluid.bridge.handleRequest('verifyBonusCode', async ({ code }) => {
        // ...
    });
};
document.head.appendChild(script);
```

Do **not** set `script.async = true` — async loading defers execution, so `window.fluid.bridge` may not exist when your `onload` callback runs. For framework-specific examples (e.g. React `useEffect`), see [Framework integrations](https://docs.fluidpayments.io/docs/integration-manual/framework-integrations).

### Defensive fallback: queue-drain shim

If your integration cannot guarantee that handler registration happens after the script loads (e.g. handlers are registered at module scope in a bundled app), you can install a lightweight shim **before** loading the Fluid script:

```html
<script>
    window.fluid = window.fluid || {};
    window.fluid.bridge = window.fluid.bridge || {
        __queue: [],
        handleRequest(method, handler) { this.__queue.push([method, handler]); }
    };
</script>
```

On init the widget captures any queued `handleRequest` calls and replays them into the real handler registry. This is a defensive fallback — the recommended approaches are the inline `<script>` tag or the `onload` callback above.
## Limitations

- There is no per-request timeout configuration — the 5000ms timeout applies to all methods.
- The handler registry is shared across all widget instances on the page. If more than one Fluid widget element is present simultaneously, they share the same handlers.

---

# Introduction to Managing Fluid

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/intro

Welcome to the Fluid Back Office documentation! At Fluid, we use [DatoCMS](https://dashboard.datocms.com/) as our central tool for managing all aspects of the product.

When onboarded, operators will receive access to the Fluid project in DatoCMS. This access enables them to manage and customize the Fluid wallet for their own brand(s), tailoring it to their specific needs.

## Accessing the Fluid Project

Once logged in to DatoCMS, there will be a list of projects. Look for the project named "Fluid", and click "Enter Project" to begin managing the Fluid profile.

Alternatively, the Fluid project can be directly accessed by visiting: [https://fluid.admin.datocms.com](https://fluid.admin.datocms.com).

![Screenshot of DatoCMS Homepage](https://docs.fluidpayments.io/img/backoffice-guide/introduction/datocms.png)

---

# Settings

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/settings/overview

## Managing the Brands

In the Settings section, operators will find an overview of the brands associated with their Fluid DatoCMS profile. These brands are assigned to them by Fluid and can be managed through this interface.

To begin managing a brand, simply click on the brand name from the list on the initial Settings page.

## Name

This is the name assigned to the operator’s Brand in the Fluid DatoCMS project. The name serves as an identifier within the backoffice. It has been set by Fluid and should not be changed.

## AI Features

Fluid offers a suite of AI Features to help operators customise deposit journeys for their customers.

Click [here](fluid-artificial-intelligence.md) to learn more about our AI Features.

## Amounts

### Hide min/max Amount

By default, the wallet shows the min and max limits as helper text directly under the amount input, so customers know the accepted range at a glance. Some operators prefer a cleaner amount step that only surfaces a limit once it actually applies to the customer.

Enabling **Hide min/max Amount** changes the behavior on the **deposit** flow to:

- The min and max helper text is **hidden on initial load**, regardless of the default amount.
- The **min** value appears only when the customer enters an amount **below the minimum**.
- The **max** value appears only when the customer enters an amount **above the maximum**.
- As soon as the entered amount is back within the accepted range, both helpers are hidden again.

To prevent any layout jump when an error appears, the space beneath the input is reserved even while no helper is shown — the input itself never shifts.

> **Note:** A short delay is applied before an error message appears, so customers don't see a brief red flash while still typing (e.g. typing "200" against a minimum of 20 will not show "below min" while passing through "2" or "20").

> **Scope:** This setting applies to the **deposit** flow only. The **withdrawal** flow always shows the min and max limits, so customers know the maximum amount they can take out.

As set in the back office:

![Screenshot of Hide min/max amount in Backoffice](https://docs.fluidpayments.io/img/backoffice-guide/settings/overview/hide-min-max-amount.png)

As displayed in the wallet when disabled:

![Screenshot of Wallet with min/max amount](https://docs.fluidpayments.io/img/backoffice-guide/settings/overview/amount-input-with-min-max.png)

As displayed in the wallet when enabled:

![Screenshot of Wallet without min/max amount](https://docs.fluidpayments.io/img/backoffice-guide/settings/overview/amount-input-without-min-max.png)

### Predefined Amounts

Amounts can be predefined and managed for different currencies, as well as suggest alternative options for customers.

To start using Predefined amounts, click on “New Predefined Amount” and fill in the:

- **Currency**: Specify the currency for which the predefined amounts apply.
- **Default Deposit Amount**: Set the default amount to be shown to the customer.
- **Suggested Deposit Amounts**: Provide additional amounts as alternative options for the customer.

Example:

As set in the back office:

![Screenshot of Amounts in Backoffice](https://docs.fluidpayments.io/img/backoffice-guide/settings/overview/predefinedamountsdato.png)

As displayed in the wallet:

![Screenshot of Wallet Amounts](https://docs.fluidpayments.io/img/backoffice-guide/settings/overview/amount-input-screenshot.png)

## Payments

Here, you can configure settings related to transaction fees and autofill options. Additionally, you can manage API credentials for the Admin API.

### Player Fees Hidden

When customers are on the Payment Method Selection or Summary screens, transaction fees are displayed, if applicable. By enabling the “Player Fees Hidden” toggle:

- Fees will be hidden from customers.
- The “Countries with Hidden Fees” field will become available.

By default, fees are hidden for all markets. If your brand operates in multiple markets, you can specify which countries to hide fees for by listing their **3-letter Alpha-3 codes**, separated by commas.

### Autofill Credit Card Name

If a fullname property is being passed in the Data User Object, you have the ability to pre-populate the “Name on Card” field in the card details step by enabling the “Autofill Credit Card Name”.

### Number of the characters of the holder's name

You can set a limit to the number of characters that the user can utilize in the “Name on Card” field.

### Admin API Client ID & Admin API Client Secret

These credentials are required for the PaymentIQ admin API.

The credentials will be used for Data Correction and Data Monitoring, which will be used to generate reports.

### Display Full List of Deposit Methods

A first time depositor will see 3 payment methods in addition to an expandable view for additional payment methods. If you switch this toggle on, a first time depositor will be shown the full list of available payment methods.

## KYC

Fluid also has the ability to provide restrictions and possible actions according to the customer’s KYC (Know your customer) status. This can be enabled by switching the toggle on.

Click [here](kyc-user-verification-flow.mdx) to learn more about the KYC feature.

## Visual Configuration

### Balance Displayed

Within the wallet, the customer’s balance is shown in the header. This feature can be disabled by switching the toggle off.

### Transaction Toggle Displayed

The wallet includes a toggle feature in the header, allowing customers to switch between payment types: Deposit and Withdrawal.

This toggle can be disabled if not required by setting the toggle option to "off."

### Bonus Outline

Add an outline to the bonus component when a bonus is selected for improved visibility.

### Express Deposit Flow

The Express Deposit Flow is a streamlined deposit experience for first-time depositors (users without saved payment methods). When enabled, the customer sees the amount input, payment method selection, and bonus selection on a single screen, then proceeds directly to the payment details step — skipping the separate bonus and method selection steps.

By default, first-time depositors go through a multi-step flow:

1. Amount
2. Bonus
3. Payment method
4. Details

![Screenshot of the Standard Flow on step 1 — amount input only](https://docs.fluidpayments.io/img/backoffice-guide/settings/visual-configuration/standard-flow-amount-first.png)

_Standard Flow on step 1: amount input only. The customer then proceeds through bonus, payment method, and details on subsequent steps._

With Express Deposit Flow enabled, this becomes:

1. Amount + payment method + bonus (combined)
2. Details

![Screenshot of the Express Flow on step 1 — amount, payment method selection, and bonus combined on a single screen](https://docs.fluidpayments.io/img/backoffice-guide/settings/visual-configuration/express-flow.png)

_Express Flow on step 1: amount input, payment method selection, and bonus selection combined on a single screen._

This feature does not affect users with stored payment methods — they continue to use their existing flow.

#### How to Set Up

- Enable or Disable the feature by switching On/Off the **"Express Flow :zap:"** toggle.
- Specify which markets should use the Express Flow by listing their **3-letter Alpha-3 codes** in the **"Countries with Express Flow"** field, separated by commas.
    - Example: `GBR, DEU, FRA`
    - If the toggle is on but no countries are listed, the Express Flow is enabled for everyone.
    - If the toggle is on and countries are listed, the Express Flow is only enabled for customers whose country is in the list.

### Wallet Position

The Fluid wallet can be positioned in multiple ways, based on your preference and UI requirements. The available options are:

1. #### Drawer on the Left
    - The wallet slides out from the left side of the screen.
    - It occupies the left side of the window.

2. #### Centered
    - The wallet slides out from the bottom of the window.
    - It occupies the center of the screen.

3. #### Drawer on the Right
    - The wallet slides out from the right side of the screen.
    - It occupies the right side of the window.

**For these drawer-style positions, an inline style is added to the `body` tag to prevent scrolling:**

`style="overflow: hidden; touch-action: none;"`

4. #### Embedded within as inline elements

In this configuration, the wallet is embedded within a container element.

##### Key Characteristics:

- No Animation: Animations for this position must be applied to the parent element if required.
- No Close Button: The close button is removed from the header.
- No Inline Style: The `body` tag is not modified with inline styles.

##### Container and Wrapper Guidelines:

- The wallet occupies 100% of its container using the following styles:

```css
inline-size: 100%;
block-size: 100%;
```

- To control the dimensions of the wallet, define the inline-size or block-size properties on the wrapper (parent element).
- Scrolling is handled inside the wallet, so there is no need to set an overflow property on the wrapper.

##### Responsive Design Recommendations

- Small Devices
    - Use absolute positioning for the wrapper to ensure it covers the entire viewport.
    - Minimum width: 320px.
- Tablet Layout
    - Activated at 480px.
    - The wrapper should have either an inline-size or block-size defined.
- Maximum Size
    - The maximum inline size (max-inline-size) for the wrapper is 439px.
    - Larger wrappers are unnecessary.

```CSS
.wrapper-widget {
    position: fixed;
    inset: 0;

    @media only screen and (min-width: 480px) {
        block-size: 600px; // Or 100vh
        inline-size: 440px;
        position: relative;

    }
}
```

#### Scroll behavior

By default, the wallet uses the CSS property [overscroll-behavior: contain](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overscroll-behavior), so that scrolling is kept in the wallet.
If scrolling past the wallet limits is required, you can enable, [you can enable overscroll-behavior-auto](https://docs.fluidpayments.io/docs/integration-manual/fluid-widget-integration.mdx).

### Delay to Waiting Approval (Hours)

When a customer opens their wallet, Fluid retrieves all pending withdrawals that have not yet been processed by the provider. These withdrawals are displayed to the customer, each accompanied by a progress bar reflecting the transaction's status. Additionally, customers are provided the option to "Cancel Withdrawal."

The withdrawal progress bar is a visual indicator designed to enhance user experience by showing the status of a withdrawal request. This feature tracks the progress of a withdrawal request through three stages and updates automatically based on the time elapsed since the request was initiated.

#### Progress Bar Stages

The progress bar consists of three sequential stages:

1. Requested: The withdrawal request has been submitted by the customer.
2. Processing: The withdrawal is in the process of being handled.
3. Approved: The withdrawal has been approved by the provider. _However this will never be shown to the customer, as transactions that have already been processed would not be retrieved._

#### Setting Up the Delay to "Processing"

You can configure the delay before a withdrawal transitions to the **Processing** state by specifying the number of hours in the Delay to Waiting Approval field. This field defines the time threshold for moving a withdrawal from the Requested state to Processing if the withdrawal has not yet been processed by the provider.

##### Steps to Configure:

- Navigate to the Delay to Waiting Approval (Hours) input field.
- Enter the desired number of hours that must elapse before a withdrawal transitions to the "Processing" state.

#### How it works

- When a customer initiates a withdrawal, it immediately enters the **Requested** state.
- If the customer reopens their wallet and the provider has not yet processed the withdrawal:
    - The progress bar will display the **Processing** state if the specified delay threshold (hours) has been exceeded. Otherwise, the state will remain on **Requested**.

#### Example Workflow

1. A customer requests a withdrawal at 10:00 AM.
2. The Delay to Waiting Approval is set to 2 hours.
3. At 12:01 PM, if the wallet is reopened and the withdrawal is still unprocessed, the progress bar transitions to Processing.

> **Notes**
>
> - The progress bar is a visual feature to provide clarity on the withdrawal status but does not affect the underlying transaction process.
> - Customers can cancel their withdrawal at any time before it is approved by the provider.

## Contact and Reports

### Send Reports

Fluid offers the capability to receive daily BIN reports conveniently via email. These reports are automatically sent every day at 05:00 AM GMT.

#### How to Enable Daily Reports

To enable this feature, simply toggle the reporting option to "On" in the settings.

#### Reporting Email

- Specify the email address where the reports should be delivered.
    - Multiple recipients can be added. Each email address should be separated by a comma.

### Contact Support Link

When a transaction is unsuccessful, operators can provide users with a convenient way to get in touch by displaying a "Contact Us" button. Clicking this button Fluid will send a notification to the Operator and can open the user’s default email application with the recipient’s email address pre-filled.

#### How to Setup

- Enable or Disable feature by switching On/Off the toggle "Contact Support enabled".
- If the "Contact Support link (optional)" is left blank, the button will have no action bound to it and Fluid will only send a notification to the operator.
- To enable the “Contact Us” button to start an email contact, populate the "Contact Support link (optional)" field.
    - Use the “mailto:” tag, followed with the email address for the desired point of contact.
        - Example: mailto:support@test.com

## Pending Withdrawals Reminder

By default, when a user attempts to deposit while having 1 (or more) pending withdrawals, Fluid will show a message to the player advising that they have pending withdrawals and give the option to cancel any pending withdrawal. However, this prompt can simply be ignored and the user can continue with their deposit.

Enabling this feature will allow you to enforce user interaction with this prompt, so that it cannot be ignored. Should the feature be enabled, the user will have to:

- Dismiss the prompt and continue with their deposit, or;
- Cancel any pending withdrawal(s).
    - Continue with the deposit flow or dismiss the cashier.

### How to Setup

- Enable or Disable the feature by switching On/Off the toggle "User response required for pending withdrawals".
- Define the number of pending withdrawals needed before enforcing interaction with the prompt in the "Pending withdrawals threshold for user response" input field.

> **Additional Notes**
>
> **Save Changes:** Always click “Save” after making edits to ensure updates are applied.

---

# Fluid Artificial Intelligence (AI)

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/settings/fluid-artificial-intelligence

Fluid offers three AI-powered features that can be utilized independently or in combination:

- Predictions for Deposit Methods Order
- Predictions for Suggested Amounts
- A/B Testing

Any of these features can be enabled from the Settings page in the back office by toggling their respective switches.

>**Note:** Before enabling any of the AI features historical data is required to perform Machine Learning (ML) and/or Data Analytics (DA).

## Predictions for Deposit Methods Order

This feature determines the optimal order of payment methods displayed during the payment method selection step, improving the deposit experience through predictive analytics.

To generate predictions, the following parameters must be available:
- Country (ML and DA)
- Age (ML)

If any required parameters are missing or data volume is insufficient, the system defaults to the pre-configured payment method order.

## Predictions for Suggested Amounts

This feature predicts and displays tailored deposit amounts, including default and alternative suggestions, based on historical data and customer behavior.

The following parameters are necessary for generating predictions:
- Country (ML and DA)
- Currency (ML and DA)
- Previous Deposit (ML)

In cases where parameters are unavailable or the data volume is insufficient, pre-set default amounts configured in the back office will be used.

### AI Model Configuration

When enabled, a dropdown menu for the AI model appears, providing three options:
- **Low**: Suggested amounts align closely with predictions.
- **Medium**: Suggested amounts are moderately higher than predictions.
- **High**: Suggested amounts are significantly higher than predictions.

## A/B Testing

This feature facilitates testing of various AI models for Predictions for Suggested Amounts, enabling data-driven decisions on model selection.

### Setup

- Divide the traffic split among the Low, Medium, High or No AI models to see which performs best.
- To do this, specify the proportions of the desired split between the different models.
    - Assign a number for each AI model.
    - Use the same values if an equal distribution is desired.
- Scenario 1 (using percentages - values add up to 100):
    - Low - 25
    - Medium - 25
    - High - 25
    - No AI - 25

    ![Screenshot of A/B Testing](https://docs.fluidpayments.io/img/backoffice-guide/settings/fluid-artificial-intelligence/ab-testing.png)

- Scenario 2 (not using percentages):
    - Low - 4
    - Medium - 6
    - High - 5
    - No AI - 5

### Split Adjustment

Whatever values are specified, Fluid will make the necessary adjustments to calculate the correct proportions to 100% of the traffic.

For instance, using scenario 2 as an example, our system would calculate the sum of the values as 20 and adjust the split for each model as follows:
- Low - 20% (4/20)
- Medium - 30% (6/20)
- High - 25% (5/20)
- No AI - 25% (5/20)

#### Recommendations

- Percentages should be split evenly between the selected AI models for balanced testing.
- A/B Testing should remain active for at least four weeks without modifications to collect sufficient data for analysis.

>**Important:** Enabling A/B Testing overrides any active Predictions for Suggested Amounts configuration.

---

# KYC User Verification Flow

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/settings/kyc-user-verification-flow

Fluid provides the capability to integrate KYC (Know Your Customer) user verification directly into the Fluid widget. This integration helps enforce deposit restrictions based on verification status and ensures compliance with regulatory requirements.

## Parameters for KYC Checks

Fluid uses the following parameters to determine whether KYC checks are required and what actions to take:

- **Deposit Limit Per Currency:** The maximum amount a user can deposit in a specific currency before verification is required.
- **User Lifetime Deposit:** The total amount the user has deposited so far across all transactions.
- **User KYC Status:** The current verification status of the user.

## KYC Action Scenarios

Based on the user's KYC status and deposit history, the system will handle the deposit flow as follows:

1. Limit Not Reached:

    If the user's lifetime deposit has not exceeded the deposit limit for the currency, they will be:
    - Prompted in the chat box to complete verification.
    - Shown the maximum amount they can deposit before verification is mandatory.

![Screenshot of Limit not reached](https://docs.fluidpayments.io/img/backoffice-guide/settings/kyc-user-verification-flow/kyc-limit-input.png)

2. Limit Reached:

    If the user's lifetime deposit equals or exceeds the deposit limit, they will be:
    - Prompted in the chat box to complete verification.

![Screenshot of Limit reached](https://docs.fluidpayments.io/img/backoffice-guide/settings/kyc-user-verification-flow/kyc-limit-reached.png)

3. Verification in Progress:

    If the user's verification process is already underway, they will be:
    - Notified that verification is being processed.
    - Advised to close the wallet while waiting for verification completion.

![Screenshot of verification in progress](https://docs.fluidpayments.io/img/backoffice-guide/settings/kyc-user-verification-flow/verification-in-progress.png)

## Configuration Steps

To enable and configure KYC user verification, follow these steps:

1. Set Deposit Limits:
    - Navigate to the Settings page in the back office.
    - Define a Deposit Limit Per Currency for each currency requiring KYC checks.

2. Pass Required Data:
    - When invoking the Fluid widget, include the following properties in the FluidUserData object:
        - `lifetimeDeposit:` The user's total deposit amount.
        - `kycStatus:` The user's current KYC status.

## KYC Status Representation

The `kycStatus` field uses an enum from the [@fluidpayments/types](https://www.npmjs.com/package/@fluidpayments/types) package. The possible values are:

```typescript
export enum FluidKycStatus {
    VERIFIED = 'verified',
    UNVERIFIED = 'unverified',
    PROCESSING = 'processing'
}
```

---

# Campaign

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/campaign

Campaigns let the operator enable a themed experience for a limited
period — for example, a football World Cup campaign. Campaigns are
created by the Fluid team; the operator picks one from the library and
sets an expiration date.

A campaign is assigned to the operator from the **Visual Configuration**
section of the **Settings** menu, together with an **Active until** date.
Only one campaign is active at a time. The campaign is automatically
deactivated once the _Active until_ date is reached.

## Assigning a campaign

The operator goes to **Settings → Visual Configuration** and scrolls to the
**Campaign** field, then picks a campaign from the dropdown.

Below the campaign selector, set the **Active until** date and time. The
campaign will automatically deactivate after this date. Use **Clear** to
remove the date.

![Screenshot of the Campaign field and Active until date in Visual Configuration](https://docs.fluidpayments.io/img/backoffice-guide/campaign/campaign-assign.png)
![Screenshot of the Campaign dropdown listing existing campaigns](https://docs.fluidpayments.io/img/backoffice-guide/campaign/campaign-dropdown.png)

## Campaign features

Each campaign created by the Fluid team can include the following
features:

- **Success screen animation** — a themed animation played on the
  deposit and withdrawal success screens.
- **Custom chat icons** — themed icons that override the theme
  [Step Icons](theme#step-icons) in the chat box.

> **Additional Notes**
>
> **Expiration:** Once the _Active until_ date set in the Visual
> Configuration section is reached, the campaign is deactivated
> automatically — there is no need to remove the assignment.
>
> **Need a new campaign?** Contact the Fluid team to have a new
> campaign created and added to your library.

---

# Content

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/content

The Content tab in the back office provides complete control over the text content of the wallet. It is designed to empower users to customize every detail, ensuring the cashier aligns perfectly with the brand's identity and user experience goals.

## Key Features

1. Modular Customization:

    - The Content tab is divided into multiple sections, each representing a specific component or functionality of the cashier.
    - Customization options are modular, allowing targeted updates to specific areas without affecting unrelated components.

2. Consistent Editing Workflow:

    - Most features in the Content tab follow a similar editing pattern:
        - Labels: Modify text labels displayed to users (e.g., button names, headings).
        - Behavior: Define user interactions.

3. Real-Time Previews:

    - Changes made within the Content tab can be previewed in real-time (where applicable), reducing the guesswork and enabling rapid iteration.

## Common Customization Options

The following are the primary categories of customizable features available within the Content tab:

- Edit text strings for headings, buttons, error messages, and tooltips.
- Supports multi-language configurations to cater to diverse user demographics.
- Use of placeholder text for input fields.

## How to Use the Content Tab

1. Locate the Feature:
    - Use the search bar to quickly find a specific feature by name or description.
    - Alternatively, navigate through the structured sections to explore all customization options.
2. Edit the Settings:
    - Make the necessary changes.
3. Save:
    - Save changes to apply them. Click the "Save" button in the top right corner.

---

# Error

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/error

The Error tab allows for managing any error that might occur while the user is making a transaction according to the error code provided by the payment provider and managing user experience.

Users can add, view, edit and delete errors from their collection.

## View Error collection

- This tab displays all errors in the operator’s collection.

## Add an Error to collection

- To add a new error to the collection:
    1. Click the “+ New Record” button in the top right corner. This will load a new screen.
    2. Populate all input fields
        - Code - Used solely within the back office to identify this error.
        - Text Title - The error label which will be displayed to the user.
        - Text - The message displayed to the user.
        - Provider Error Codes - Add all provider error codes (comma separated) that should be grouped under this error.
        - Error Action - From the drop down menu, select what kind of action should the customer be provided with when using the “Try again” functionality.
            - Restart process and clear details - The customer will restart the whole process from scratch.
            - Restart process and preserve details - The customer will be taken to the initial screen, but should they not change their payment method, they will not have to input their details.
            - Show details step and clear details - The customer will be taken to the details step, and will be presented with blank fields.
            - Show details step and preserve details - The customer will be taken to the details step and will be presented with the same details they have just used.
        - Icon Selection - Select the icon to be displayed to the customer for this error.
        - Faulty Transaction Filter

            This functionality allows for blocks on further attempts from the user for a defined period of time, with:
            - The same payment method
            - Equal or higher amount

            We suggest that for any error where it is likely to immediately re-occur if no changes are made, this feature is enabled.

            For example; When the provider returns “ERR_DECLINED_NO_FUNDS”, if the user tries again immediately and makes no changes to the amount or payment method, it is highly likely that the attempt will be unsuccessful once again.
            - Switch on the toggle to enable
                - Populate the newly provided field with the duration (in seconds) for which further attempts should be prevented.

## Edit an error in collection

- Locate the error which requires editing.
- Click the error code. The screen with its details will be displayed.
- Edit as necessary.

## Delete an error from collection

- Locate the error to be deleted.
- Click the error code. The screen with its details will be displayed.
- Navigate to and click the options menu (3 dots) next to the header, in the top left corner.
- Click “Delete”.

>**Additional Notes**
>
>**Save Changes:** Always click “Save” after making edits to ensure updates are applied.
>
>**Search Tip:** Use the Find functionality to quickly find specific errors in large collections.

---

# Input fields

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/input-fields

Fluid offers the operators the possibility of customizing the input fields being present to the customers in the wallet.

In this tab, the operators can view, add, edit and delete input fields within their collection.

## Viewing Input Fields

- This tab displays all input fields in the operator’s collection.

## Add an Input Field to collection

- To add a new Input Field to the collection:
    - Click the “+ New Record” button in the top right corner. This will load a new screen.
    - Populate all input fields
        - **Internal Name*** - Used solely within the back office to identify this input field.
        - **Param Name*** - The name that will be used to pass this parameter.
        - **Text** - How the field is labelled to the user.
        - **Place Holder Text** - Any text that should be displayed in the input field until populated by the user.
        - **Error Text** - What message to show to the customer if a mistake is identified in the input field.
        - **Format** - The expected format of the data inserted in the field. Format is defined using regular expressions.
        - **Options** - Add all options for which this input field should be used.
    - Disable/Enable Toggles as needed:
        - **Field is optional** - Enable if the field can be left empty and doesn't require user interaction.
        - **Prefill** - Enable if you wish to add a value by default and define the value to add.
        - **Remove + sign from phone number prefix** - Enable if the input field is for phone numbers and you wish to not have the "+" added to the prefix value when sent to the payment orchestrator.
        - **Treat as password** - Enable if the value entered in this field should be hidden (masked) as the user types, like a password. The customer can tap the eye icon to reveal or hide the value. Disabled by default.

## Edit Input Fields from collection

- Locate the input field which requires editing.
- Click the input field name. The screen with its details will be displayed.
- Edit as necessary.

## Delete Input Fields from collection

- Locate the input field to be deleted.
- Click the input field name. The screen with its details will be displayed.
- Navigate to and click the options menu (3 dots) next to the header, in the top left corner.
- Click “Delete”.

>**Additional Notes**
>
>**Save Changes:** Always click “Save” after making edits to ensure updates are applied.
>
>**Search Tip:** Use the Find functionality to quickly find specific input fields in large collections.
>
>**Mandatory fields:** All fields with a “*” are mandatory.

---

# Operator Errors

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/operator-errors

The Operator errors tab allows the operator to manage their existing errors. Operators can view, add, remove, or edit payment methods from their collection.

## Viewing errors

- This tab displays all active errors from the operator's collection.

## Adding Errors

- To add an error to the active list:
- Click inside the “Errors” field.
- Select the error:
    - Type the method name in the search box, or
    - Scroll through the presented dropdown menu.
- The selected error will be added to the active list.

## Removing Errors

- To remove an active error:
- Locate the error in the “Errors” field.
- Click the “x” button next to the error name.

## Editing Active Errors

- To edit an active error:
- Click the name of the error.
- A new window will pop out. Make the necessary changes.
- Click “Save” in the top-right corner to apply the changes.

>**Additional Notes**
>
>**Save Changes:** Always click “Save” after making edits to ensure updates are applied.
>
>**Search Tip:** Use the Find functionality to quickly find specific errors in large collections.

---

# Operator Payment Methods

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/operator-payment-methods

The Operator Payment Methods tab allows managing active payment methods efficiently. Operators can view, add, remove, or edit payment methods from their collection.

## Viewing Active Payment Methods

- This tab displays all currently active payment methods from the operator's collection.

## Adding Payment Methods

- To add a payment method to the active list:

    1. Click inside the “Payment Methods” field.
    2. Select the method:
        - Type the method name in the search box, or
        - Scroll through the presented dropdown menu.
    3. The selected payment method will be added to the active list.

## Removing Payment Methods

- To remove an active payment method:
    1. Locate the desired payment method in the “Payment Methods” field.
    2. Click the “x” button next to the method name.

## Editing Active Payment Methods

- To edit an active payment method:
    1. Click the name of the payment method.
    2. A new window will appear. Make the necessary changes.
    3. Click “Save” in the top-right corner to apply the changes.

>**Additional Notes**
>
>**Save Changes:** Always click “Save” after making edits to ensure updates are applied.
>
>**Search Tip:** Use the Find functionality to quickly find specific payment methods in large collections.

---

# Option

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/option

Some payment methods may have several options available to them. The option tab offers the possibility of managing the different options that an operator might need.

In this tab, the operators can view, add, edit and delete input fields within their collection.

## Viewing Options

- This tab displays all options in the operator’s collection.

## Add an option to collection

- To add a new option to the collection:
    - Click the “+ New Record” button in the top right corner. This will load a new screen.
    - Populate all input fields
        - Label - How this option is presented to the customers.
        - Name - Used solely within the back office to identify this option.
        - Code - The code to represent this option.
        - Logo - An image to represent this option.

## Edit an option from collection

- Locate the option which requires editing.
- Click the option name. The screen with its details will be displayed.
- Edit as necessary.

## Delete Input Fields from collection

- Locate the option to be deleted.
- Click the option name. The screen with its details will be displayed.
- Navigate to and click the options menu (3 dots) next to the header, in the top left corner.
- Click “Delete”.

>**Additional Notes**
>
>**Save Changes:** Always click “Save” after making edits to ensure updates are applied.
>
>**Search Tip:** Use the Find functionality to quickly find specific input fields in large collections.

---

# Payment Method

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/payment-method

Fluid provides its customers the facility to create payment methods as required from the Payment Method page.

When a payment method is created, it will be added to the operator’s collection to use when needed.

## View Payment Methods

- This tab displays all payment methods in the operator’s collection.

## Creating a new Payment Method

- To add a new payment method:
    1. Click on the “+ New Record” button in the top right corner. This will open a new page.
    2. Populate the fields presented.
        - **Name*** - This field will define the payment method's name the end-users see when they use the wallet.
            - Use the locale tabs to provide a name for your payment method (in case the name is different and requires translations).
            - This field accepts single-line text input. Both uppercase and lowercase letters are accepted.
        - **Name (Internal)*** - This field is for internal use only and helps distinguish between payment method names from different providers.
            - Naming should follow the following format: **PROVIDERTYPE_SERVICE-OperatorName**.
        - **Provider Type*** - This field will define the transaction type used to set up the payment method in your Payment Orchestration platform. The transaction type in this field should be identical to the one you are using on your platform.
        - **Service** - This field will help you to separate APMs or providers with the same transaction type and in the cashier these methods will be with their own logo and name. (this field can be left empty if you are using only one Transaction Type)
        - **Logo and Logo Light** - This field allows you to upload .svg format logos directly from your computer or the Media library on your Fluid account.
            - _Logo **has to be in SVG format** with dimensions 94 x 56_
        - **Terms & Conditions** - This field allows you to add single line free text. (for example: interac-trademark)
        - **Masked account format** - The dropdown list lets you determine how much of the stored method details is shown to the user.
        - **Info** - This field is used to display information about the payment method. An “i” icon will be shown next to the payment method when any information is added.

        ![Text content customized](https://docs.fluidpayments.io/img/backoffice-guide/payment-method/payment-info-dato.png)

        ![Text content customized](https://docs.fluidpayments.io/img/backoffice-guide/payment-method/payment-info-wallet.png)

        - **Auto-Redirect Type** - Enables auto-redirect for this method. When enabled, users are automatically redirected (if required) without any manual action.
        Select the container type (Popup Window or Browser Tab) that matches the method configuration.
        - **Payment Type*** - The dropdown list has 4 selections to choose from.
            - EWallet
            - BankTransfer
            - Crypto
            - CreditCard
        - **Instructions (Payment method HTML)** - The field is used to add an HTML or Markdown and to add optional usage instructions for any payment method.

        ![Text content customized](https://docs.fluidpayments.io/img/backoffice-guide/payment-method/html-instructions.png)

        - **Deposit Input Fields** - This field is used to specify any additional fields required by the payment method.

            Input fields are selected from the 'Library,' and a 'New Input Field' can be added if the Library does not have the desired value. 'Amount' and 'service' do not need to be specified in this section, as they are provided by default as part of the deposit flow.
        - **Withdrawal Input Fields** - This field is used to specify any additional fields required by the payment method. (same as 'Deposit Input Fields') Please note that the same Payment method entry can be used in case Provider Type & Service are the same for Deposit and Withdrawal. Input fields are selected from the 'Library,' and a 'New Input Field' can be added if the Library does not have the desired value. 'Amount' and 'service' do not need to be specified in this section, as they are provided by default as part of the deposit flow.
        - **Withdrawal inputs shown when method is stored** - This toggle can be switched when the player should be presented with the Input Fields even if they're using a stored method.
        - **Payment Limits** - Optional per-method deposit and withdrawal limits. The record exposes four numeric fields:
            - **Min Deposit** - Minimum amount a player can deposit using this method.
            - **Max Deposit** - Maximum amount a player can deposit using this method.
            - **Min Withdrawal** - Minimum amount a player can withdraw using this method.
            - **Max Withdrawal** - Maximum amount a player can withdraw using this method.

            Each field is optional. A value set here only applies when the payment provider does **not** return its own limit for the method — provider-supplied limits always win. Leaving a field empty (or setting it to `0`) tells Fluid to fall back further to its global default. Use this record to define sensible per-method limits on gateways that don't return their own (for example Payage).

> Attributes marked with * are mandatory.

## Edit payment methods in collection

- Locate the payment method which requires editing.
- Click the payment method. The screen with its details will be displayed.
- Edit as necessary.

## Delete payment methods from collection

- Locate the payment method to be deleted.
- Click the payment method. The screen with its details will be displayed.
Navigate to and click the options menu (3 dots) next to the header, in the top left corner.
- Click “Delete”.

>**Additional Notes**
>
>**Save Changes:** Always click “Save” after making edits to ensure updates are applied.
>
>**Search Tip:** Use the Find functionality to quickly find specific payment methods in large collections.

---

# Success Screen

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/success-screen

The Success Screen tab in the Fluid back office allows the display of promotions to customers following a successful transaction. Multiple promotions can run in parallel across different markets, but if a country has more than one promotion assigned, only the topmost promotion will be displayed, while the rest will be disregarded.

## Managing promotions:

- Creating a promotion
    1. Click the “+ New Promotion” button at the bottom of the page.

        Alternatively, duplicate an existing promotion by clicking on the “more options” menu (three dots icon) next to the promotion header.

    2. Populate all of the presented fields:
        - Countries - Countries (Alpha-3 code) should be comma separated. Promotion would be shown to the player only if the cashier is opened in this country.
        - User Tags - These are the tags that can be passed as part of the userDataObject. Promotion would be shown to the player only if the cashier is opened with these userTags passed as a parameter.
        - Title - Title of promotion shown on screen.
        - Description - Short promotion description/message shown on screen.
        - Tag - Displayed in the top-left corner of the promotion. Example: Featured Game, or Free Spins!
        - CTA Link Label - Text shown on promotion button.
        - CTA Link Url - URL to redirect to the promotion.
        - Thumbnail - Upload the image to display for the promotion.
            - Thumbnail should be in 2:1 ratio.

![Screenshot of Success Screen setup](https://docs.fluidpayments.io/img/backoffice-guide/success-screen/success-screen.png)

- Edit an existing promotion
    1. Navigate to the corresponding promotion.
    2. Apply changes as needed.

- Delete a promotion
    1. Navigate to the corresponding promotion.
    2. Click on the “more options” menu (three dots icon) next to the promotion header and select “Remove Block”.

> **Important:** When changes are made to the Success Screen page, click the “Save” button in the top right corner to apply the changes.

![Screenshot of Success Screen promotion](https://docs.fluidpayments.io/img/backoffice-guide/success-screen/success-screen-promotion.jpg)

> **Additional Notes**
>
> **Promotion Priority:** If multiple promotions are assigned to the same country, the promotion listed at the top will take precedence. Reorder promotions as necessary to reflect priorities. Promotions can be reordered using the “more options” menu (three dots icon) next to the promotion header.
>
> **Default Behavior:** If no countries are specified, the promotion will automatically apply to all markets.

---

# Theme

> Source: https://docs.fluidpayments.io/docs/backoffice-guide/theme

Fluid allows for customisation of the wallet to match the brand’s visual identity.

The following aspects of the wallet can be customised:

- Options
- Colours
- Step Icons
- Success Sound
- Bonus Image
- Font Weight

## Options

### Button Style

Choose from three distinct button styles:

- Pill

![Screenshot of Success Screen setup](https://docs.fluidpayments.io/img/backoffice-guide/theme/pill.png)

- Rounded

![Screenshot of Success Screen setup](https://docs.fluidpayments.io/img/backoffice-guide/theme/rounded.png)

- Square

![Screenshot of Success Screen setup](https://docs.fluidpayments.io/img/backoffice-guide/theme/square.png)

### Gradient Direction

In the Color Button section, you can define a value for `Color Button Base Stop` (and `Color Button Hover Stop`). When set, the primary button is rendered with a gradient going from `Color Button` to `Color Button Base Stop` (and from `Color Button Hover` to `Color Button Hover Stop` on hover).

The gradient direction is controlled by the `Gradient Direction` dropdown, which offers two options:

- `Vertical` (default) — gradient runs top to bottom
- `Horizontal` — gradient runs left to right

### Inline Quick Deposit Border Radius

You can set a pixel value for the border radius of the [Inline Quick Deposit widget](https://docs.fluidpayments.io/docs/integration-manual/fluid-quick-deposit-integration).
The value by default is 12px.

## Colours

Customize the colors for up to 12 wallet components:

- Backgrounds
- Text
- Primary - Used for links, info text, radio inputs, active input fields, selected state border on payment selector
- Button
- Pill - Amount selector
- Status
- Overlay - For popups, modals and background when wallet is open on desktop.
- Input
- Progress Bar
- Icon
- Borders/Dividers
- Card Input

## Step Icons

Icons can be configured for the following steps:

- Amount
- Bonus
- Payment Method
- Secure
- Checking Details

## Bonus Image

Set a default image as a placeholder for any bonus that lacks a specific image.

## Sound

Set a custom sound to be played for successful transactions.

## Font Weight

While the font itself is inherited from the website, the font weight has a default value.

- Default value:
- Medium: 400
- Semi-bold: 600
- Bold: 700

However, these values can be modified to match the brand’s own values.