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 have multiple states. When state event occurs, it meant that the Widget has changed it's state. Every kind of state have to be handled.

opened

This state signals that Widget just has opened and begun to load, but 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 Widget inside 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 client tries to close the widget. Note, that in case of Custom Iframe Integration the closed state not means that Widget already closed; instead it have to be handled by closing 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 client's transaction was completed.

rejected

This state signals that 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 upwards. This event does not mean that in SDK is able to catch all possible errors, but mean that certain specific errors can be catched and handled. At this moment, only two exceptions emits:

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

payment-initiated

Payload: empty object

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

On this event, you have to close widget, perform payment and open widget again with 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. On this event, you have to redirect user to provided redirect URL with aim to complete 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 the Widget, Bridgerpay used when user choose certain payment providers. Bridgerpay redirects users to a BP iframe which is outside Paybis control. In the Paybis SDK these events handled properly, but in case of integration with custom iframe it's mandatory to handle it manually to ensure a smooth experience, users must be redirected back successfully.

To handle Bridgerpay event, listen for it and update the iframe's src to the provided URL, completing the payment process.

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;
}