Web 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 (or any other) 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 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 example below illustrating the JavaScript SDK integration.:
<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>
<button onclick="openWidget()">Transfer crypto</button>
function openWidget() {
// Pay attention that for this step partner already needs to have requestId
window.PartnerExchangeWidget.open({
requestId: '<genereated unique requestId>',
})
}
Web SDK options
🧭Widget Initialization Options
Name | Arguments | Returns | Details |
---|---|---|---|
open() | requestId *oneTimeToken ** | void | Opens widget UI in iFrame full-screen overlay (default behavior). |
openInIframe() | requestId *oneTimeToken ** | void | Opens the widget UI in iFrame full-screen overlay. |
openInEmbed() | requestId *oneTimeToken **element | void | Opens the widget UI in embedded mode inside the passed element . |
detectAndOpen() | requestId *oneTimeToken ** | void | Opens 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. |
openInNewTab() | requestId *oneTimeToken ** | void | Opens 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, openInNewTab event is cancelled due to browser security restrictions and the Widget UI does not open. |
openRedirect() | requestId *oneTimeToken ** | void | Opens the widget UI by redirecting the user from the partner's website to the widget URL (in the same browser tab). |
⚙️ SDK Configuration Parameters
Parameter / Method | Type | Description |
---|---|---|
close() | function | Closes the widget manually. Works only if the widget was opened via open , openInEmbed , or openInIframe . |
state | enum | Returns the current state of the widget. E.g., initialized , loading , loaded , etc. |
isLoaded | boolean | Indicates whether the SDK has finished loading. |
events | object | Contains all available SDK event listeners (e.g. onclosed , onloaded , etc.). |
isSafari() | function | Utility method that returns true if the current browser is Safari. |
📣 Internal SDK Events
These events are available via PartnerExchangeWidget.events
and help you track key moments in the widget lifecycle to customize your flow.
Event | When it triggers | Description |
---|---|---|
onopened | When the widget starts to open (before loading completes) | Useful for tracking UI opening start |
onloaded | When the widget is fully loaded and ready | Indicates that the user can start interacting |
onclosed | When the user closes the widget manually | Triggered by “Close” button |
onerror | On any error | Passes an error object |
oncompleted | When the transaction completes successfully | |
oncancelled | When the transaction is cancelled by the user | |
onrejected | When the transaction is rejected | |
onstartnewtransaction | When a new transaction is initiated from within the widget | You can handle this depending on the flow in your app: e.g. re-open the widget with a new session, or, for example, redirect the user somewhere within your application. |
onpayoutwaiting | When transaction enters payout-waiting status | Indicates payout process has started |
onpaymentinitiated | When a payment is confirmed inside the widget (Sell Crypto flow) | Confirms user action |
⏳UI Loader Parameters
Parameter | Type | Description | Default |
---|---|---|---|
loader | boolean / object | Controls the display of the widget’s loading screen. | true |
loader: true | — | Enables the default preloader UI (with standard background and animation). | |
loader: false | — | Disables the default preloader UI — partner is responsible for showing a custom loader externally. | |
loader.imageSrc | string | (When loader is object) Path to a custom image used in the widget’s loader. Must be publicly accessible. | — |
loader.styles | object | Allows overriding styles of the loader (e.g., background color). | — |
loader.styles.backgroundColor | string | Background color of the loader (supports any valid CSS color string). | 'rgba(0,0,0,0.4)' |
Updated 13 days ago