Attributes

The three Fluid custom elements share most of their attributes. In the table below, Widget refers to <fluid-widget>, QD is <fluid-quick-deposit>, and Virtual is <fluid-virtual>.

Note

Attributes marked required are mandatory for Automatic Init. When using Programmatic Init, these are provided to fluid.init() instead and can be omitted from the element — except session-id, which should always be bound on the element so the widget picks up session rotations. See Session Handling.

Full attribute reference

Attribute	Widget	QD	Virtual	Description
operator-id	Required	Required	Required	Unique operator identifier, provided by Fluid Payments. Must match the value in your Operator Config
session-id	Required	Required	Required	Current session ID of the authenticated user. See Session Handling
user-id	Required	Required	Required	Identifier of the authenticated user
locale	Required	Required	Required	IETF BCP 47 locale tag (e.g. en-NZ, es-MX). en and ar are valid shorthands. POSIX-style underscores normalised automatically (en_GB → en-GB). If the value is still invalid, the widget falls back to en and emits invalid-init-attributes
currency	Required	Required	Required	ISO 4217 currency code. For Virtual, this is the FIAT currency
country	Required	Required	Required	ISO 3166-1 Alpha-3 country code
user-data	Optional	Optional	Optional	FluidUserData object, stringified as JSON. See User Data
transaction	Optional	—	Optional	deposit | withdrawal | quick-deposit
lock-transaction-type	Optional	—	Optional	When true, user cannot switch transaction type
open	Optional	—	Optional	true / false — controls wallet visibility. Not used by QD, which is always visible while mounted
balance	Optional	—	Optional	Widget: current balance. Virtual: VirtualBalance object as JSON (see Virtual Balance)
withdrawable-balance	Optional	—	—	Amount available to withdraw
bonuses	Optional	Optional	—	Stringified bonus data array. See Bonus Data. On QD this is a performance optimisation: the bonuses are processed once and become available in the main widget
transaction-limits	Optional	Optional	Optional	Stringified JSON object capping how much the player can deposit or withdraw, each with an optional message of your own. See Transaction Limits
success-cta-link	Optional	—	Optional	Link recorded with the Play now click on the success screen, for tracking only. The widget never navigates to it: Play now emits success-cta-click (fluid-info, with no link) followed by a close command, and your page decides what happens next
z-index	Optional	Optional	Optional	Stacking order for overlay display
turned-over-percentage	Optional	—	Optional	Turned over percentage; hidden if not provided
transaction-attributes	Optional	Optional	Optional	Stringified JSON of key-value pairs sent to the payment provider
deposit-amount	Optional	Optional	Optional	Pre-filled deposit amount (overrides configured defaults)
allow-decimal-amounts	Optional	Optional	Optional	Defaults to "true". Set to "false" to restrict deposit amounts to whole numbers: a decimal separator can’t be typed or pasted (entering 10.50 leaves 10) and mobile devices show a digits-only keypad. Applies to deposit entry only — deposit, quick deposit, the payment details screen and the Sweepstakes custom amount. Withdrawal and redemption amounts always accept decimals. Amounts you supply are never rounded, so make sure deposit-amount, your suggested amounts and your pack prices are whole numbers too
prefilled-bonus-code	Optional	—	—	Pre-fills the manual bonus code input. Requires Manual Bonus Codes to be enabled. The code isn’t validated automatically: the user must click Apply to trigger verification through the Bridge API
two-factor-auth-enabled	Optional	—	—	"true" adds a 2FA step to the withdrawal flow. Per-player flag: set it according to whether the player has 2FA enabled. See Two-Factor Authentication
overscroll-behavior-auto	Optional	—	—	Sets overscroll-behavior: auto for the inline cashier
withdrawal-warning	Optional	—	—	Stringified JSON object with custom withdrawal warning. See Withdrawal Warning
virtual-currencies	—	—	Required	VirtualCurrencies object as JSON. See Virtual Currencies
packs	—	—	Optional	Stringified packs data. See Packs

Numeric values

balance, withdrawable-balance, turned-over-percentage and deposit-amount (and the deprecated deposit-limit) are read with the decimal separator of the locale set on the element, so you can write an amount the way your players read it.

On <fluid-virtual> this covers deposit-amount and turned-over-percentage only. Its balance is a stringified VirtualBalance object rather than a single amount (see Data Objects), and withdrawable-balance is not supported there. The amounts inside that object are JSON numbers, so they take a dot and no grouping whatever the locale: "primaryBalance": 10.5, never "primaryBalance": "10,5".

• A dot is accepted on every locale. deposit-amount="10.50" is 10.5 whatever the locale.
• A comma is accepted where the locale uses one as its decimal separator. With locale="fr", deposit-amount="10,50" is also 10.5.
• Digit grouping is accepted when it can only be read one way. "1,500" is 1500 on locale="en", "1 500,25" is 1500.25 on locale="fr", and "1,500.25" is 1500.25 on either. A space is only read where it stands between digit groups, so "1 2" is rejected rather than treated as 12.
• Grouping must match the shape your locale writes. Most locales group in threes. The Indian locales (en-IN, hi-IN) group in lakhs, so "12,34,567" is 1234567 there, and "1,234,567" is rejected on en-IN, just as "12,34,567" is rejected on en. This applies to spaces as well as commas.
• Locales that write their own digits are read in those digits too. With locale="ar-EG", deposit-amount="١٠٫٥٠" is 10.5. ASCII digits keep working on every locale.
• Values are never rounded. What you send is what the widget uses.

Check what your locale actually uses before assuming it takes a comma, because the language is not a reliable guide. ar (default Arabic), es-MX and th are dot-decimal, while en-ZA and ar-MA are comma-decimal, and de-CH groups with an apostrophe (both ' and ’ are read, so "1'500" and "1’500" are both 1500). A locale reads the digits of the numbering system the browser resolves for it and no other: Arabic-Indic on ar-EG and ar-SA, Perso-Arabic on fa, Bengali on bn, Devanagari on mr and ne. ar, ar-MA, hi, hi-IN, ta, pa and ml all resolve to Latin digits, so on those you must write ASCII digits, and on ar, a dot.

Browsers disagree on some locales. Safari resolves bn, mr and ne to Latin digits where Chrome and Firefox use their own scripts, so a value in Bengali or Devanagari digits is read on Chrome and Firefox and rejected on Safari. fr-CH is comma-decimal on Chrome and Firefox but dot-decimal on Safari, so deposit-amount="10,50" on locale="fr-CH" is 10.5 on Chrome and rejected on Safari. If your players span browsers, ASCII digits with a dot are the one notation every browser accepts.

One separator between digits is always a decimal

This is the one case where a value meant as thousands becomes a fraction instead:

• On every locale, "1.500" is 1.5, including the locales that group with dots. A single dot with no comma is always a decimal point. Several dots are read as grouping, so "1.500.000" is 1500000.
• On a comma-decimal locale, "1,500" is 1.5 and "100,000" is 100. If you write English thousands grouping on locale="fr" or locale="de", you will pre-fill or cap at a thousandth of what you meant, and no fluid-error is emitted, because the value reads perfectly well as a decimal.

Write whole thousands unseparated (1500, 100000), or group them the way the locale does ("1.500,00" on de, "1 500,00" on fr, "1,00,000" on en-IN).

A value that can’t be read as one unambiguous number is ignored, and the widget keeps its previous value or its configured default. This includes "10,50" on locale="en", where the comma is neither a valid decimal separator nor a valid grouping. The widget emits a fluid-error event with message invalid-init-attributes and a reason naming the attribute and the value, so a rejected amount reaches your error handling. An attribute that is empty or absent is not a rejection: it is treated as unset, restores the default behaviour, and emits nothing.

Reactive (observed) attributes

Always observed while open

Attribute	Behaviour
open	Triggers wallet visibility
balance / withdrawable-balance	Updates balance information in real time
session-id	Ensures a consistently valid user session
withdrawal-warning	Updates the warning on the withdrawal screen (Widget only)
packs	Updates packs data including selected pack (Virtual only)
allow-decimal-amounts	Switches the deposit amount fields between decimal and whole-number entry. It only affects what the player types next, so changing it mid-flow is safe

Observed only while wallet is closed

Attribute	Behaviour
transaction	Updates the transaction type
lock-transaction-type	Locks the transaction type
bonuses	Updates bonus information (Widget only; QD reads once at mount)
transaction-limits	Updates the deposit and withdrawal limits and their messages
deposit-limit	Updates the deposit limit (deprecated)
deposit-amount	Updates pre-filled amount; unset to restore defaults
user-data	Updates data for AI-suggested Deposit Amounts and KYC
success-cta-link	Sets the post-success CTA link
turned-over-percentage	Sets the turned over percentage
transaction-attributes	Updates transaction attributes
prefilled-bonus-code	Pre-fills the bonus code input (Widget only)
two-factor-auth-enabled	Toggles the 2FA step (Widget only)

Caution

Changes to the “closed-only” group made while the wallet is open are not applied immediately — they take effect the next time the wallet opens. This ensures the transaction flow is not interrupted by changes on the host site.

The exception is transaction: while the wallet is open, the active flow is the source of truth and the widget writes its current transaction type back to the attribute.

Quick Deposit special behaviour

The inline <fluid-quick-deposit> is always visible while mounted. It reacts to changes of transaction-limits (and the deprecated deposit-limit), user-data, transaction-attributes and allow-decimal-amounts. Every other attribute, including session-id and bonuses, is read once at mount and requires a re-mount to change.

Deprecated attributes

These still work and are not scheduled for removal. Do not use them in a new integration.

Attribute	Replaced by	Notes
deposit-limit	transaction-limits	A responsible gaming deposit limit, as a plain number. It has no message of its own and does not cover withdrawals. It follows the same numeric rules as the attributes above, and is read while the wallet is closed. If you send both, the lower of the two applies.