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
Updated about 1 month ago