The Trustly SDK provides an addPanelListener function which is used to track user events within the Trustly Lightbox experience. This function is also essential for intercepting the standard browser redirects (returnUrl and cancelUrl) in order to process those final events with JavaScript callbacks directly within your Single Page Application (SPA).

Supported notifications and event types

You can use the addPanelListener function to provide a custom handler to deal with Lightbox events.

The JavaScript window event notification call below only works on native apps when the Trustly SDK is used or if the merchant implements the creation of new windows.

Listener example

Trustly.addPanelListener((command, obj) => {
  switch(command) {
    case "open":
      console.log("Lightbox will open");
      break;

    case "event":
      switch(obj.type) {
        case "load":
          console.log(
            "Lightbox page " + obj.page +
            " finished loading for transaction " +
            obj.transactionId
          );
          break;

        case "bank_selected":
          console.log(
            "Payment provider having id " + obj.data +
            " was selected on the page " + obj.page +
            " for transaction " + obj.transactionId
          );
          break;

        case "back":
          console.log(
            "Back button was clicked on the lightbox page " +
            obj.page + " for transaction " + obj.transactionId
          );
          break;

        case "close":
          console.log(
            "Lightbox close process was initiated " +
            "on the lightbox page " + obj.page +
            " with reason " + obj.data +
            " for transaction " + obj.transactionId
          );
          break;

        case "new_location":
          console.log("Browser will be redirected to " + obj.data);
          break;
      }
      break;

    case "close":
      console.log("Lightbox was closed");
      break;
  }
});

Command and event reference

The listener receives two parameters: the high-level command (open, close, event) and the detailed object data.

The following table details the high-level commands and specific event types, along with the data they contain, that can be intercepted using the addPanelListener function.

Command/Event Type	Command/Type Data	Description
`open` (Command)	-	Triggered immediately when the Trustly Lightbox opens.
`close` (Command)	-	Triggered when the Trustly Lightbox finishes closing.
`event` (Command)	-	Triggered when a specific user action or internal change occurs within the Lightbox.
`load` (Event)	`{ page, transactionId }`	Triggered when a specific page finishes loading. `page` contains the name of the loaded page.
`loading` (Event)	`{ page, transactionId }`	Triggered when page content loading is active. This can be useful for displaying spinners or progress indicators.
`bank_selected` (Event)	`{ page, transactionId, data, transfer }`	Triggered when a user selects a bank tile. `data` is the `paymentProviderId`. `transfer.paymentProvider` contains the bank details (ID and name).
`back` (Event)	`{ page, transactionId }`	Triggered when a user clicks the back button or navigates to the previous page in the flow.
`close` (Event)	`{ page, transactionId, data: reason }`	Triggered when the Lightbox close process is initiated. `reason` will be `"return"` or `"cancel"`.
`new_location` (Event)	`{ data: newLocation }`	Crucial for SPA integration. Triggered when the flow is complete and the user is about to be redirected to the `returnUrl` or `cancelUrl`. `newLocation` contains the final URL with return parameters. You can process the final result using this data and prevent the browser redirect.