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/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/partner-wallets.js";const t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})()}}();
</script>
Production environment inject https://wallets.paybis.com/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.paybis.com/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
argument will open the Application. Usage example:
window.PartnerWalletsSDK.open({
sessionId: '<generated unique sessionId>',
});
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 with sessionId
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
Name | Type | Details |
---|---|---|
events | object | Object that contain callbacks for SDK events. |
events.onOpened | function | This 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.onLoaded | function | This event signals that the Plug&Play Wallets application has been opened and it's data has successfully loaded |
events.onClosed | function | This event occurs when the user closes the application by clicking the "close" button |
events.onError | function | By 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 |
loader | boolean | object | Defines 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.imageSrc | string | Path to the preloader image. Ensure that the image is stored on publicly accessible resource. |
loader.styles | object | Custom styles for preloader. |
loader.styles.backgroundColor | string | Background for preloader. Have rgba(0,0,0,0.4) as default value. |
Methods
Name | Arguments | Returns | Details |
---|---|---|---|
open | sessionId : stringoneTimeToken : stringlocale : enum | void | Opens application UI in iFrame full-screen overlay (default behavior). |
openInIframe | sessionId : stringoneTimeToken : stringlocale : enum | void | Opens the application UI in iFrame full-screen overlay. |
detectAndOpen | sessionId : stringoneTimeToken : stringlocale : enum | void | Opens 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. |
openInNewTab | sessionId : stringoneTimeToken : stringlocale : enum | void | Opens 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, openInNewTab event is cancelled due to browser security restrictions and Widget UI does not open. |
openRedirect | sessionId : stringoneTimeToken : stringlocale : enum | void | Opens the application UI by redirecting the user from partner's website to plug&play wallets URL (in the same browser tab). |
close | void | Triggers exit from the wallets UI. It can be used if wallets was initiated with openInIframe or open methods only. |
Getters
Name | Returns | Details |
---|---|---|
state | enum | Returns the current state of the application (see the list of possible states below). |
isLoaded | boolean | Shorthand for state , that indicates that the plug&play wallets app has been loaded. |
loader | boolean | object | Returns loader property. |
loaderImage | string | undefined | Path to the preloader image, if it presented. |
loaderBackground | string | undefined | Background 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 loadedstartLoading
, when Plug&Play application started to loadloaded
, when Plug&Play application is loadedcompleted
, when certain transaction inside Plug&Play was completedrejected
, when certain transaction inside Plug&Play was rejectedcancelled
, when user cancel transactionclosed
, when App requests to close, but iframe not removed yetterminated
, when App was closed and iframe was removed
Application's
state
isn't available, when the Application opened in a new tab!
Updated 8 months ago