Events & Errors

Fluid widgets communicate with the host page using CustomEvent with a detail property:

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

Listening for events

const widget = document.querySelector('fluid-widget');
widget.addEventListener('fluid-command', onFluidCommand);
widget.addEventListener('fluid-info', onFluidInfo);
widget.addEventListener('fluid-error', onFluidError);

In the tables below, Widget is <fluid-widget>, QD is <fluid-quick-deposit> and Virtual is the Sweepstakes <fluid-virtual>. On Virtual, transaction events keep their literal deposit and withdrawal names, for the purchase and redeem flows respectively.

fluid-info events

Informational messages about what happened in the widget, often so the user can act on it. They aren’t primarily designed for tracking, though the transaction events carry transactionId so you can tie them to a particular transaction.

Message	Widget	QD	Virtual	Detail fields	Description
`initialised`	Yes	Yes	Yes	—	Widget is ready to open. Do not open before this fires.
`opened`	Yes	—	Yes	—	Wallet has been opened
`destroyed`	Yes	—	Yes	—	Widget instance has been terminated
`internal-operation-change`	Yes	—	Yes	—	Transaction flow amended internally (e.g. withdrawal without balance)
`success-cta-click`	Yes	—	Yes	—	User clicked the success screen CTA
`deposit-success`	Yes	Yes	Yes	`transactionId`, `amount`, `currency`, `paymentMethod`, `bonus`, `packId` (Virtual purchases only)	Successful deposit/purchase
`deposit-failure`	Yes	Yes	Yes	`transactionId`, `amount`, `currency`, `paymentMethod`, `errorCode`, `providerCode`, `responseCode`	Failed deposit/purchase
`withdrawal-success`	Yes	—	Yes	`transactionId`, `amount`, `currency`, `paymentMethod`, `bonus`	Successful withdrawal/redemption
`withdrawal-failure`	Yes	—	Yes	`transactionId`, `amount`, `currency`, `paymentMethod`, `errorCode`, `providerCode`, `responseCode`	Failed withdrawal/redemption
`withdrawal-cancelled`	Yes	—	Yes	`withdrawalAmount`	Withdrawal/redemption cancelled
`try-again-click`	Yes	Yes	Yes	—	User clicked retry on failure screen
`contact-support`	Yes	—	Yes	—	User clicked Contact Support on failure screen
`bonus-changed`	Yes	—	—	`selectedBonusCode`, `previousBonusCode`	User changed selected deposit bonus
`payment-method-changed`	Yes	Yes	Yes	`selectedMethodName`, `previousMethodName`, `selectedMethodIsStored`	User changed payment method
`dialog-opened`	Yes	—	Yes	—	A dialog opened from the wallet
`dialog-closed`	Yes	—	Yes	—	A dialog closed from the wallet
`deposit-cta-clicked`	—	Yes	—	—	User clicked “Deposit” when no recent method available (QD only)
`close`	—	Yes	—	—	User closed the expanded Quick Deposit element. Widget and Virtual report closing through the `close` fluid-command instead
`start-kyc-verification`	Yes	—	Yes	—	Tracking counterpart of the fluid-command

fluid-error events

Unexpected failure notifications.

Message	Widget	QD	Virtual	Description
`initialisation-failure`	Yes	Yes	Yes	Could not configure (network/backend issue or missing attributes). When Fluid didn’t accept the player’s session, `detail` also carries `code: 'SESSION_REJECTED'` and a `reason`; when it couldn’t check the session for now, `code: 'SESSION_CHECK_UNAVAILABLE'`. See A refused session
`operation-execution-failure`	Yes	—	Yes	Operation failed unexpectedly
`gateway-configuration-error`	Yes	—	Yes	Orchestrator configuration for the operator could not be fully resolved. The cashier shows the problem to the user; contact Fluid Payments if it persists
`invalid-bonus-data`	Yes	Yes	—	Bonus data format incorrect
`invalid-user-data`	Yes	Yes	Yes	User data format incorrect
`invalid-transaction-attributes`	Yes	Yes	Yes	Transaction attributes format incorrect
`invalid-init-attributes`	Yes	Yes	Yes	An attribute failed validation and the widget falls back to a safe default (for example `en` for an invalid `locale`). Also emitted for a numeric attribute that can’t be read (see Numeric values), so it can arrive well after initialisation. On Virtual, also emitted for malformed `virtual-currencies`, `balance` or `packs` and for an unknown `transaction` value. The rejected value is ignored; an empty or absent attribute emits nothing. The `reason` detail field describes the problem. With `fluid.init()` the call rejects instead, except for the numeric attributes, which always report through this event
`invalid-transaction-limits`	Yes	Yes	Yes	`transaction-limits` could not be read. If the value is not valid JSON, the widget keeps the limits it already had; if only part of it is unusable (e.g. a limit that is not a number), the rest still applies and one event is emitted per problem. See Transaction Limits
`invalid-withdrawal-warning`	Yes	—	—	`withdrawal-warning` could not be parsed as JSON

fluid-command events

Actions requiring a response from the host site.

Message	Widget	QD	Virtual	Detail fields	Description
`close`	Yes	—	Yes	—	User wants to close the wallet. Set `open` to `false`.
`handle-transaction`	Yes	Yes	Yes	`amount`, `method`, `bonus`, `transaction`	Emitted instead of Fluid processing the transaction when the payment method is configured for host-side completion. `method` is the payment method name, `bonus` the bonus code (when applicable) and `transaction` the transaction type. Your page takes over the flow from there
`start-kyc-verification`	Yes	—	Yes	—	User clicked Verify in the identity verification prompt
`withdrawal-warning-cta-clicked`	Yes	—	—	—	User clicked the CTA in the withdrawal warning

When the widget needs data from your page and a typed response — for example to validate a bonus code — it uses the Window Bridge API instead of events.