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 triggers	Description
`opened`	When the widget starts opening	Equivalent to `onopened` in SDK
`loaded`	When the widget is fully loaded	Equivalent to `onloaded` in SDK
`closed`	When the user attempts to close the widget	Needs to be handled manually in custom iframe setups
`completed`	When the transaction is successfully completed
`rejected`	When the transaction is rejected
`cancelled`	When the transaction is cancelled by the user
`showLoader`	When widget requests to show a preloader externally	Used during transaction switch or frictionless flows
`hideLoader`	When widget requests to hide the external preloader	Complements `showLoader`
`start-new-transaction`	When user clicks "Start new transaction" inside embedded widget	Used in embedded integrations to trigger new request flow
`error`	When a specific handled error occurs inside the widget	Contains detailed error info (message, type, etc.)
`payment-initiated`	When user initiates crypto payment (Sell crypto Frictionless flow)	Used in `partner_controlled_with_sdk_event` mode. Requires external payment (crypto payment) flow handling
`payment-redirect`	When 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