Web: Javascript SDK

Installation guide

JS script injection

The widget functionality can be included in the partner app through the injection of JS script. Example:

<script>
!function(){if(window.PartnerExchangeWidget=window.PartnerExchangeWidget||{open(e){window.partnerWidgetSettings={immediateOpen:e}}},"PartnerExchangeWidget"!==window.PartnerExchangeWidget.constructor.name){(()=>{const e=document.createElement("script");e.type="text/javascript",e.defer=!0,e.src="https://widget.sandbox.paybis.com/partner-exchange-widget.js";const t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})()}}();
</script>
<script>
!function(){if(window.PartnerExchangeWidget=window.PartnerExchangeWidget||{open(e){window.partnerWidgetSettings={immediateOpen:e}}},"PartnerExchangeWidget"!==window.PartnerExchangeWidget.constructor.name){(()=>{const e=document.createElement("script");e.type="text/javascript",e.defer=!0,e.src="https://widget.paybis.com/partner-exchange-widget.js";const t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})()}}();
</script>

You can call the window.PartnerExchangeWidget.open method with requestId any time after the script is injected on the page. The widget’s UI will be rendered as soon as the Open method is called. Example:

<script>
  !function(){if(window.PartnerExchangeWidget=window.PartnerExchangeWidget||{open(e){window.partnerWidgetSettings={immediateOpen:e}}},"PartnerExchangeWidget"!==window.PartnerExchangeWidget.constructor.name){(()=>{const e=document.createElement("script");e.type="text/javascript",e.defer=!0,e.src="/partner-exchange-widget.js";const t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})()}}();
  window.PartnerExchangeWidget.open({
    requestId: '<genereated unique requestId>', 
  });
</script>

🚧

For the pages that are rendered on a server, the widget’s UI will be displayed immediately after the HTML page is loaded.

Widget JS SDK usage example

This approach can be used in cases where a partner website uses AJAX requests for communication between the client and server. It means that the website doesn’t reload the HTML to get the data, but uses Javascript for updating it. In that case, the PartnerExchangeWidget provides plenty of APIs for handling all possible cases.

🚧

Please take special care during implementation. To run this code, you need to be sure that the PartnerExchangeWidget was loaded completely.

Note the examples below illustrating the JavaScript SDK integration.

In your HTML code:

<script>
  !function(){if(window.PartnerExchangeWidget=window.PartnerExchangeWidget||{open(e){window.partnerWidgetSettings={immediateOpen:e}}},"PartnerExchangeWidget"!==window.PartnerExchangeWidget.constructor.name){(()=>{const e=document.createElement("script");e.type="text/javascript",e.defer=!0,e.src="/partner-exchange-widget.js";const t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})()}}();
</script>

Or like so in your HTML code:

<button onclick="openWidget()">Transfer crypto</button>

Or inside of your own custom javascript code:

function openWidget() {
  // Pay attention that for this step partner already needs to have requestId
  window.PartnerExchangeWidget.open({
    requestId: '<genereated unique requestId>', 
  })
}

Helpful tips

  1. Responsiveness

Include the "viewport" meta tag in the HTML file where the widget is initialized to ensure optimal responsiveness across various screen resolutions:

`<meta name="viewport" content="width=device-width, initial-scale=1.0">`
  1. Permissions inside the iframe

Purchase flow in the Paybis widget involves the online payment and KYC verification process that requires access to the browser camera, microphone, and keyboard on the user's device. To ensure that the access permissions will properly work within the iframe, add the allow attribute with the following values when creating an iframe element:

`<iframe src="[enter-your-url]" allow="clipboard-read; clipboard-write *; payment *; camera; microphone;" />`

  1. Enabling Apple Pay in Cross-Origin iFrames

To utilize Apple Pay within an iframe that's loaded from a different origin (website domain) than Partner's main application, allow="payment" attribute should be added to the <iframe> tag. This attribute signals to the browser that the iframe requires access to payment-related functionalities, including Apple Pay.
Example:

<iframe src="[enter-your-url]" allow="payment"></iframe>

By adding this attribute, the iframe is granted the necessary permissions to initiate and complete Apple Pay transactions, even when embedded in a cross-origin context.

📘

The allow="payment"attribute is a relatively new feature and may not be fully supported by all browsers (Safari 17 and later).

  1. Google Pay and Apple Pay in WebView integration

In WebWiew integration, set the pb-mob-app cookie to true so that the Google Pay / Apple Pay popup triggers redirect to a regular mobile browser. This is required for Google Pay and Apple Pay to work properly in this integration type.

Javascript SDK options

NameArgumentsReturnsDetails
openrequestId*
oneTimeToken**
voidOpens widget UI in iFrame full-screen overlay (default behavior).
openInIframerequestId*
oneTimeToken**
voidOpens the widget UI in iFrame full-screen overlay.
openInEmbedrequestId*
oneTimeToken**
element
voidOpens the widget UI in embedded mode inside the passed element.
detectAndOpenrequestId*
oneTimeToken**
voidOpens the widget UI using the best appropriate method depending on the user's browser:

- new browser tab option applies to Safari users;
- iFrame option applies to all browser users except Safari);
- The redirect (same tab) option applies to Safari users if the new tab fails to open due to browser restrictions.
openInNewTabrequestId*
oneTimeToken**
voidOpens the widget UI in a new browser tab.
Important: ensure that there are no asynchronous actions (e.g. requests to the backend) between the user's click on the button initiating Widget and Widget open. Otherwise, openInNewTabevent is cancelled due to browser security restrictions and the Widget UI does not open.
openRedirectrequestId*
oneTimeToken**
voidOpens the widget UI by redirecting the user from the partner's website to the widget URL (in the same browser tab).
isLoadedbooleanIndicates that the widget SDK has been loaded.
stateenumReturns the current state of the widget (see the list of possible states below).
closevoidTriggers exit from the widget UI. It can be used if the widget was initiated with openInIframe, openInEmbed or open methods only.
eventsobjectAll listeners of events that SDK emits can be placed in this object.
events.onopenedvoidThis event is emitted when the application has opened (by user or programmatically), but the loading has just begun. Time may pass between the onopened and onloaded events
events.onloadedvoidThis event signals that the Widget application has been opened and its data has successfully loaded
events.onclosedvoidThis event occurs when the user closes the application by clicking the "close" button
events.onerrorvoidBy listening to this event, you can respond to exceptional situations that the user may encounter while working with the application. For example, when the user is blocked or hasn't permission to access cookies in his browser
events.onpaymentinitiatedvoidIndicates that the payment has been initiated and a user has confirmed the transaction summary in the widget. Relevant for Sell crypto flow only.
loaderboolean/object

Default value: true
Defines the preloader option that will apply on widget start:

- true: default preloader is used;
- false: default preloader is hidden, the partner can use custom preloader;
- object: default loader (background and image) is customized.
loader.imageSrcstring (path to image)Path to the preloader image. Ensure that the image is stored on publicly accessible resources.
loader.stylesobjectCustom styles for preloader.
loader.styles.backgroundColorstring

Default value: [‘rgba(0,0,0,0.4)’]
Background for preloader.