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

NameArgumentsReturnsDetails
open()requestId*
oneTimeToken**
voidOpens widget UI in iFrame full-screen overlay (default behavior).
openInIframe()requestId*
oneTimeToken**
voidOpens the widget UI in iFrame full-screen overlay.
openInEmbed()requestId*
oneTimeToken**
element
voidOpens the widget UI in embedded mode inside the passed element.
detectAndOpen()requestId*
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.
openInNewTab()requestId*
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.
openRedirect()requestId*
oneTimeToken**
voidOpens 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 / MethodTypeDescription
close()functionCloses the widget manually. Works only if the widget was opened via open, openInEmbed, or openInIframe.
stateenumReturns the current state of the widget. E.g., initialized, loading, loaded, etc.
isLoadedbooleanIndicates whether the SDK has finished loading.
eventsobjectContains all available SDK event listeners (e.g. onclosed, onloaded, etc.).
isSafari()functionUtility 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.

EventWhen it triggersDescription
onopenedWhen the widget starts to open (before loading completes)Useful for tracking UI opening start
onloadedWhen the widget is fully loaded and readyIndicates that the user can start interacting
onclosedWhen the user closes the widget manuallyTriggered by “Close” button
onerrorOn any errorPasses an error object
oncompletedWhen the transaction completes successfully
oncancelledWhen the transaction is cancelled by the user
onrejectedWhen the transaction is rejected
onstartnewtransactionWhen a new transaction is initiated from within the widgetYou 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.
onpayoutwaitingWhen transaction enters payout-waiting statusIndicates payout process has started
onpaymentinitiatedWhen a payment is confirmed inside the widget (Sell Crypto flow)Confirms user action

⏳UI Loader Parameters

ParameterTypeDescriptionDefault
loaderboolean / objectControls the display of the widget’s loading screen.true
loader: trueEnables the default preloader UI (with standard background and animation).
loader: falseDisables the default preloader UI — partner is responsible for showing a custom loader externally.
loader.imageSrcstring(When loader is object) Path to a custom image used in the widget’s loader. Must be publicly accessible.
loader.stylesobjectAllows overriding styles of the loader (e.g., background color).
loader.styles.backgroundColorstringBackground color of the loader (supports any valid CSS color string).'rgba(0,0,0,0.4)'