Internal Events

🚧

Warning! Do not confuse Internal Events, which are handled at the SDK level, with events that are handled at the SDK integration level (by passing event listeners to the SDK constructor). This section is intended for integration without SDK only.

For SDK-based event handling, see the Web SDK guide

When the Widget is launched in an iframe, it communicates with the SDK through the postMessage interface. When performing custom integration without using the Paybis SDK, it is imperative to process each of these events in order to provide the user with a UX identical to what the SDK provides.

If the widget is open in another tab, events cannot be listened.

Handling Widget Events

📨 List of the Widget Events via postMessage

These events are emitted from the Widget to the parent window and should be handled using window.addEventListener('message', ...).

Event name (event.data.name)When it triggersDescription
openedWhen the widget starts openingEquivalent to onopened in SDK
loadedWhen the widget is fully loadedEquivalent to onloaded in SDK
closedWhen the user attempts to close the widgetNeeds to be handled manually in custom iframe setups
completedWhen the transaction is successfully completed
rejectedWhen the transaction is rejected
cancelledWhen the transaction is cancelled by the user
showLoaderWhen widget requests to show a preloader externallyUsed during transaction switch or frictionless flows
hideLoaderWhen widget requests to hide the external preloaderComplements showLoader
start-new-transactionWhen user clicks "Start new transaction" inside embedded widgetUsed in embedded integrations to trigger new request flow
errorWhen a specific handled error occurs inside the widgetContains detailed error info (message, type, etc.)
payment-initiatedWhen user initiates crypto payment (Sell crypto Frictionless flow)Used in partner_controlled_with_sdk_event mode.
Requires external payment (crypto payment) flow handling
payment-redirectWhen widget provides a URL to redirect user to complete payment
(Sell crypto Frictionless flow)
Used in partner_controlled_with_redirect mode

👉 You can find examples of handling events in the Recipes section