Standalone Integration Guide

Description

This guide explains how to integrate the Paybis Ramps into your platform using Standalone Mode. This method allows you to embed the Paybis Ramps directly onto your page with minimal coding.

Prerequisites

• Obtain your Partner UUID from your Paybis integration manager.
• Generate a security signature. See the guide on Generating HMAC Signatures for detailed instructions.

Summary

To integrate the widget in Standalone Mode, you need to:

• Embed the Widget Web SDK script on your page.
• Obtain your Partner UUID and generate the required security signature.
• Use the window.PartnerExchangeWidget.open method with the necessary parameters to launch the widget.

Integration Guide

1. Embed the Widget Web SDK.

Embed the Widget Web SDK script in your webpage by adding the following code. This will load the widget on your page:

<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 = true;
        e.src = "https://widget.sandbox.paybis.com/partner-exchange-widget.js"; // For Sandbox
        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 = true;
        e.src = "https://widget.paybis.com/partner-exchange-widget.js"; // For Production
        const t = document.getElementsByTagName("script")[0];
        t.parentNode.insertBefore(e, t);
      })();
    }
  }();
</script>

2. Generate Signature and Open the Widget.

Once the SDK is embedded, generate the signature and call the window.PartnerExchangeWidget.open method with the partnerId and signature parameters:

<!-- Ensure the PartnerExchangeWidget script is loaded before this script block. -->
<script>
  window.PartnerExchangeWidget.open({
    partnerId: '<your partner UUID>',
    signature: '<generated signature>',
  });
</script>

📘

Note: Partner UUID will be provided to you during the onboarding process. You will also need to generate the signature as part of the security process. For details on how to generate the signature, please refer to the documentation here.

Examples

Here are some complete integration examples to help you get started.

<!-- Ensure the PartnerExchangeWidget script is loaded before this script block. -->
<script>
  window.PartnerExchangeWidget.open({
    partnerId: '<your partner UUID>',
    signature: '<generated signature>',
  });
</script>

<!-- Ensure the PartnerExchangeWidget script is loaded before this script block. -->
<script>
  window.PartnerExchangeWidget.open({
    partnerId: '<your partner UUID>',
    signature: '<generated signature>',
    cryptoAddress: '<crypto wallet address>',
    currencyCodeFrom: 'USD',
    currencyCodeTo: 'BTC',
    amountFrom: '10',
  });
</script>

Supported Parameters

The open method accepts additional parameters, which allows to pre-fill specific parts of user's flow. For example:

• To start the widget with the user's crypto wallet, pass the cryptoAddress, currencyCodeFrom, currencyCodeTo.
• to start the widget with the quote, pass the currencyCodeFrom, currencyCodeTo, amountFrom or amountTo.
• to define the transaction flow (buy or sell), use the transactionFlow parameter.

💱 Transaction Flow & Currency Parameters

When setting a fiat currency in the widget (the currency the user pays or receives), it is also required to specify the cryptocurrency. The widget cannot determine the fiat currency in isolation — the crypto side of the transaction must always be defined.

• Buy Crypto (transactionFlow=buyCrypto or not provided):
  To define the fiat currency the user spends (e.g. currencyCodeFrom=EUR), you must also define the crypto they will receive (e.g. currencyCodeTo=ETH).
  Example:
  https://widget.paybis.com/?currencyCodeFrom=EUR&currencyCodeTo=ETH&partnerId={partner UUID}&transactionFlow=buyCrypto&signature={signature}
  *If transactionFlow is omitted, it defaults to buyCrypto.
• Sell Crypto (transactionFlow=sellCrypto)
  To define the fiat currency the user receives (e.g. currencyCodeTo=USD), you must also define the crypto the user will sell (e.g. currencyCodeFrom=BTC).
  Example:
  https://widget.paybis.com/?currencyCodeFrom=BTC&currencyCodeTo=USD&partnerId={partner UUID}&transactionFlow=sellCrypto&signature={signature}