Events and errors

All Fluid widgets emit information to the host website using CustomEvent (https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent), with the detail property containing the information. This page is the single catalogue of every event across the three widgets.

The detail property is an object with the following structure, available as the FluidNotificationDetail type in the @fluidpayments/types package:

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

message contains a string with the different event values listed below.

Add the following code to receive the events:

const fluid = document.querySelector('fluid-widget'); // or fluid-quick-deposit / fluid-virtual

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

There are three event types:

• 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 the host site should react to

In the tables below, Widget is the main <fluid-widget>, QD is <fluid-quick-deposit> and Virtual is the Sweepstakes <fluid-virtual>. For the Sweepstakes widget, the transaction related event values keep their literal deposit and withdrawal names, corresponding to the purchase and redeem flows respectively.

fluid-info

Message	Widget	QD	Virtual	Meaning
initialised	Yes	Yes	Yes	The wallet has been prepared for opening. It should not be allowed to open before this is emitted.
opened	Yes	No	Yes	The wallet has been opened.
destroyed	Yes	No	Yes	The wallet instance has been terminated.
internal-operation-change	Yes	No	Yes	The transaction flow has been amended internally, e.g. upon a withdrawal without a positive withdrawable balance.
success-cta-click	Yes	No	Yes	The user clicked on the CTA shown on the transaction success screen.
deposit-success	Yes	Yes	Yes	A successful deposit (purchase, for Sweepstakes) was made.
deposit-failure	Yes	Yes	Yes	A deposit (purchase, for Sweepstakes) attempt failed.
withdrawal-success	Yes	No	Yes	A successful withdrawal (redemption, for Sweepstakes) was made.
withdrawal-failure	Yes	No	Yes	A withdrawal (redemption, for Sweepstakes) attempt failed.
withdrawal-cancelled	Yes	No	Yes	A withdrawal (redemption, for Sweepstakes) was cancelled.
try-again-click	Yes	Yes	Yes	The user clicked on the CTA shown on the transaction failure screen.
contact-support	Yes	No	Yes	The user clicked on the Contact Support link shown on the transaction failure screen.
bonus-changed	Yes	No	No	The user changed the selected deposit bonus.
payment-method-changed	Yes	Yes	Yes	The user changed the selected payment method.
dialog-opened	Yes	No	Yes	A dialog has been opened from the wallet.
dialog-closed	Yes	No	Yes	A dialog has been closed from the wallet.
deposit-cta-clicked	No	Yes	No	The user clicked the "Deposit" button, displayed when no recent payment method is available.
close	No	Yes	No	Quick Deposit only: the user closed the expanded element. The other widgets report closing through the fluid-command of the same name.
start-kyc-verification	Yes	No	Yes	Tracking counterpart of the fluid-command of the same name; see KYC Verification.

Note that fluid-info notifications are not primarily designed for tracking, although some carry detailed information on the event. The transaction result events include transactionId (along with amount, currency, paymentMethod, bonus on success, plus errorCode, providerCode and responseCode on failure, and packId on Sweepstakes purchases), which allows stitching those events to a particular transaction. payment-method-changed carries selectedMethodName, previousMethodName and selectedMethodIsStored; bonus-changed carries selectedBonusCode and previousBonusCode.

fluid-error

Message	Widget	QD	Virtual	Meaning
initialisation-failure	Yes	Yes	Yes	Fluid was not able to configure itself, e.g. due to a network or backend issue, or missing required attributes. See Session handling.
operation-execution-failure	Yes	No	Yes	An operation failed unexpectedly due to an error.
gateway-configuration-error	Yes	No	Yes	The orchestrator configuration for the operator could not be fully resolved. The cashier surfaces the problem to the user; contact Fluid Payments if it persists.
invalid-bonus-data	Yes	Yes	No	The bonus data is not in the correct format expected.
invalid-user-data	Yes	Yes	Yes	The user data is not in the correct format expected.
invalid-transaction-attributes	Yes	Yes	Yes	The transaction attributes are not in the correct format expected.
invalid-init-attributes	Yes	Yes	Yes	An init attribute (for example the locale) failed validation; the widget falls back to a safe default (en for locale) and keeps initialising. Also emitted when deposit-amount, deposit-limit, turned-over-percentage or, on <fluid-widget>, balance or withdrawable-balance cannot be read as a number on the element's locale. See Numeric values. The rejected value is ignored and the attribute is left as you set it on the element; an empty or absent attribute is not a rejection and emits nothing. Because these attributes are reactive, the event can also arrive well after init. On the Sweepstakes widget balance is a stringified VirtualBalance object rather than a single amount, and the same message is emitted for malformed virtual-currencies, balance or packs payloads and unknown transaction values. When the widget is initialised programmatically via fluid.init(...), the call rejects with an error instead of emitting this event for the attributes you pass to it (see Programmatic Init). The numeric attributes above are not among them, so they always report through this event.
invalid-withdrawal-warning	Yes	No	No	The withdrawal-warning attribute could not be parsed as JSON. The widget renders no warning until the attribute is corrected. See Withdrawal Warning.
invalid-transaction-limits	Yes	Yes	Yes	The transaction-limits attribute could not be read. When the value is not valid JSON the widget keeps the limits it already had; when only part of the payload is unusable, such as a limit that is not a number or an entry with a message but no limit, the readable part still applies and one event is emitted per problem. See Transaction Limits.

fluid-command

Message	Widget	QD	Virtual	Meaning
close	Yes	No	Yes	The user selected to close the wallet from within; the open attribute should be set to false. Quick Deposit reports closing on the fluid-info channel instead.
handle-transaction	Yes	Yes	Yes	Emitted instead of Fluid processing the transaction, when the selected payment method is configured to be completed by the host site. The event detail carries amount, method (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	No	Yes	The user clicked on the Verify button in the identity verification prompt. Take the user into your platform's verification flow; see KYC Verification. Also emitted as fluid-info for tracking.
withdrawal-warning-cta-clicked	Yes	No	No	The 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.
handle-banner-cta-click	No	No	Yes	The user clicked on the banner on the first step of the Quick Buy flow.

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.