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)'`