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.

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

state

Payload: enum which represents the Widget's state

The Widget has multiple states. When state event occurs, it means that the Widget has changed it's state. Every kind of state has to be handled.

opened

This state signals that the Widget just has opened and begun to load, but has not loaded yet. Time may pass between the opened and loaded states. Note, that in Paybis SDK on this state emits the onopened event and shows a preloader.

loaded

This state signals that the Widget inside an iframe is completely loaded and ready to be shown. Note, that in Paybis SDK on this state emits the onloaded event removes the preloader and appears the iframe.

closed

This state signals that the client is trying to close the widget. Note, that in the case of Custom Iframe Integration the closed state does not mean that the Widget is already closed; instead, it has to be handled by closing the iframe.

const eventData = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
const { name: eventName = '', payload = {} } = eventData;

if (eventName === 'closed') {
  iframe.remove();
}

completed

This state signals that the client's transaction was completed.

rejected

This state signals that the client's transaction was rejected.

cancelled

This state signals that client's transaction was cancelled (in most cases, by client).

showLoader

This event occurs when there's a need to show the preloader outside of the Widget after the Widget has loaded. For example, when the client navigates between transactions: in that case, preloader will cover transactions switch time. In the Paybis SDK, this preloader shows. We recommend handle this event and show preloader.

const eventData = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
const { name: eventName = '', payload = {} } = eventData;

if (eventName === 'showLoader') {
  // show preloader
}

hideLoader

If a preloader, previously requested by the showLoader event has been shown, the Widget indicates with hideLoader state that this preloader needs to be hidden. This event must be handled and preloader must be hidden, because otherwise it will not be hidden at all.

const eventData = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
const { name: eventName = '', payload = {} } = eventData;

if (eventName === 'hideLoader') {
  // hide preloader! otherwise it will not be hidden after switch between transactions
}

error

Payload: { message: string; correlationId?: string; stack?: string; type?: string; }

In certain cases, the Widget emits error upward. This event does not mean that in SDK is able to catch all possible errors, but means that certain specific errors can be caught and handled. At this moment, only two exceptions emit:

1. Blocked third-party cookies
2. Translation loading error
3. Generic unhandled errors
4. Errors that occur in the transaction process

payment-initiated

Payload: empty object

Emits only in Frictionless flow, if requestId was created with parameter partner_controlled_with_sdk_event.

In this event, you have to close the widget, perform payment, and open the widget again with the samerequestId.

Read more in "Frictionless flow" chapter.

const eventData = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
const { name: eventName = '', payload = {} } = eventData;

if (eventName === 'payment-initiated') {
  console.info('User initiate payment via frictionless flow');

  // Close widget...
  iframe.remove();

  // ~ process client's payment

  // ...open widget again
}

payment-redirect

Payload: string, redirect URL

Emits only in Frictionless flow, if requestId was created with parameterpartner_controlled_with_redirect. In this event, you have to redirect the user to the provided redirect URL with aim of completing the payment.

const eventData = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
const { name: eventName = '', payload = {} } = eventData;

if (eventName === 'payment-redirect') {
  iframe.src = payload;
}

Read more in "Frictionless flow" chapter.

Handling Bridgerpay Events

In Paybis widget, Bridgerpay is used for certain payment providers, redirecting users to an external Bridgerpay's iframe.

📘

While Paybis SDK handles these events seamlessly, for custom iframe integrations, event handling from the Partner's end is required to ensure smooth integration.

In custom iframe integrations, handle Bridgerpay events by implementing a listener to capture the event, extracting the provided URL, and updating the iframe's src attribute for seamless redirection and payment completion.

const { data: eventData } = event;
const oData = typeof eventData === 'string' ? JSON.parse(eventData) : eventData;

// @see https://mcson-cy.gitbook.io/bridgerpay-documentation/reporting/event-capture
if (oData.url && oData.event === '[bp]:redirect') {
  this.getIframe.setAttribute('src', oData.url);
  return;
}