Web: Javascript SDK

Installation guide

The PNP SDK can be installed in two main ways:

  • JS script injection: This method involves adding a reference to the PNP SDK CDN URL in your project's HTML file. This is the simplest way to install the PNP SDK.
  • NPM Package: This method involves installing the PNP SDK as an NPM package in your project. This provides all of the features of the SDK, but it requires more setup than the JS injection integration method.

JS script injection

The plug&play wallets functionality can be included in the partner app through the injection of JS script. There are two examples for two environments.

Sandbox environment inject <https://wallets.sandbox.paybis.com/sdk/partner-wallets.js> script. Use it for testing and development purposes.

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

Production environment inject <https://wallets.sandbox.paybis.com/sdk/partner-wallets.js> script. Use it when integration is done and well-tested.

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

🚧

Please take special care during implementation! To call SDK methods, need to be sure that the PartnerWalletsSDK was loaded completely. To check that SDK is loaded, following condition may be used:

if (window.PartnerWalletsSDK && window.PartnerWalletsSDK.state) {
  // SDK is loaded and can be used safely
}

After that, SDK methods and properties can be called. For example, the window.PartnerWalletsSDK.open method, called with required sessionId and partnerProductId arguments will open the Application. Usage example:

window.PartnerWalletsSDK.open({
  sessionId: '<generated unique sessionId>', 
  partnerProductId: '<product id>',
});

🚧

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

NPM Integration

To use plug&play wallets SDK from NPM package, need to add it to project via npm, yarn or pnpm. The sandbox version of SDK can be installed by specifying version after package name.

npm install @paybis/pnp-wallets-sdk@sandbox --save
yarn add @paybis/pnp-wallets-sdk@sandbox
pnpm add @paybis/pnp-wallets-sdk@sandbox --save-prod

To install latest production version, just don't add package version.

npm install @paybis/pnp-wallets-sdk --save
yarn add @paybis/pnp-wallets-sdk
pnpm add @paybis/pnp-wallets-sdk --save-prod

🚧

Project must use node version >= 18.0.0, and npm version >= 6.0.0 to ensure the build completes properly.

After package will be installed, import SDK into project.

import { PartnerWalletsSDK } from '@paybis/pnp-wallets-sdk';

The PartnerWalletsSDK is a class which have all features that SDK provide. To access to SDK methods, need to create new instance of PartnerWalletsSDK.

const sdkInstance = new PartnerWalletsSDK();

Use optional first argument to pass parameters (event handlers and / or customize loader).

const sdkInstance = new PartnerWalletsSDK({
  events: {
    onOpened: () => ({}), 
  },
});

After that, you can call the sdkInstance.open method any time after the script is injected on the page. The product’s UI will be rendered as soon as the Open method is called. Example:

🚧

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

📘

Helpful Tip

Include the viewport meta tag in the HTML file where the plug&play wallets app is initialized to ensure optimal responsiveness across various screen resolutions:

<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no,interactive-widget=overlays-content">

JavaScript SDK

Constructor Arguments

NameTypeDetails
eventsobjectObject that contain callbacks for SDK events.
events.onOpenedfunctionThis event is emitted when the application is already open, but the loading process has just begun. Time may pass between the onOpened and onLoaded events
events.onLoadedfunctionThis event signals that the Plug&Play Wallets application has been opened and it's data has successfully loaded
events.onClosedfunctionThis event occurs when the user closes the application by clicking the "close" button
events.onErrorfunctionBy listening to this event, you can respond to exceptional situations that the user may encounter while working with the application. For example, when user blocked or haven't permissions to access cookies in the his browser
loaderboolean | objectDefines the preloader options that will apply on wallets start:

- true: default preloader is used;
- false: default preloader is hidden, partner can use custom preloader;
- object: default loader (background and image) is customized.
loader.imageSrcstringPath to the preloader image. Ensure that the image is stored on publicly accessible resource.
loader.stylesobjectCustom styles for preloader.
loader.styles.backgroundColorstringBackground for preloader. Have rgba(0,0,0,0.4)as default value.

Methods

NameArgumentsReturnsDetails
opensessionId: string
partnerProductId: string
oneTimeToken: string
locale: enum
voidOpens application UI in iFrame full-screen overlay (default behavior).
openInIframesessionId: string
partnerProductId: string
oneTimeToken: string
locale: enum
voidOpens the application UI in iFrame full-screen overlay.
detectAndOpensessionId: string
partnerProductId: string
oneTimeToken: string
locale: enum
voidOpens the application 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 browsers users except Safari);
- redirect (same tab) option applies to Safari users if the new tab fails to open due to browser restrictions.
openInNewTabsessionId: string
partnerProductId: string
oneTimeToken: string
locale: enum
voidOpens the application UI in a new browser tab.
Important: ensure that there are no asynchronous actions (e.g. requests to the backend) between user's click on the button initiating Wallets and Wallets open. Otherwise, openInNewTabevent is cancelled due to browser security restrictions and Widget UI does not open.
openRedirectsessionId: string
partnerProductId: string
oneTimeToken: string
locale: enum
voidOpens the application UI by redirecting the user from partner's website to plug&play wallets URL (in the same browser tab).
closevoidTriggers exit from the wallets UI. It can be used if wallets was initiated with openInIframe or open methods only.

Getters

NameReturnsDetails
stateenumReturns the current state of the application (see the list of possible states below).
isLoadedbooleanShorthand for state, that indicates that the plug&play wallets app has been loaded.
loaderboolean | objectReturns loader property.
loaderImagestring | undefinedPath to the preloader image, if it presented.
loaderBackgroundstring | undefinedBackground color of the loader, if presented.

Supported locales

Following list of locales can be used as value for locale argument: en, de, ru, it, fr, es, pt, ko

Supported state values

Plug&Play Wallets application may be in one of following state:

  • initial, when SDK just been loaded
  • startLoading, when Plug&Play application started to load
  • loaded, when Plug&Play application is loaded
  • completed, when certain transaction inside Plug&Play was completed
  • rejected, when certain transaction inside Plug&Play was rejected
  • cancelled, when user cancel transaction
  • closed, when App requests to close, but iframe not removed yet
  • terminated, when App was closed and iframe was removed

🚧

Application's state isn't available, when the Application opened in a new tab!