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>
  1. 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.
ParameterRequiredDescriptionValidation
partnerIdrequiredUnique identifier of your product. It will be provided by your account manager.valid UUID. Must match the one provided to you by your account manager.
signaturemandatoryThe security signature for the URL request. A valid signature generated using the query parameters and secret key.
cryptoAddressoptionalUser's crypto wallet address. The wallet entry screen is pre-filled if the parameter is passed. The user can confirm or change the wallet address.Must be a valid crypto wallet address.
currencyCodeFromoptionalFiat currency code for Buy crypto transactions. Cryptocurrency code for Sell crypto transactions.Must be a valid fiat or cryptocurrency code (depending on the transaction flow: buy/sell). Use the GET Currency Pairs Buy Crypto or GET Currency Pairs Sell Crypto endpoint to retrieve the list of supported currency codes.
currencyCodeTooptionalCryptocurrency code for Buy crypto transactions. Fiat currency code for Sell crypto transactions.Must be a valid fiat or cryptocurrency code (depending on the transaction flow: buy/sell). Use the GET Currency Pairs Buy Crypto or GET Currency Pairs Sell Crypto endpoint to retrieve the list of supported currency codes.
amountFromoptionalAmount in fiat that the user is going to spend for Buy crypto purchase order.

Crypto amount that the user is going to withdraw in Sell crypto flow.
Handled first. When exists and is validated - a quote is created.
amountTooptionalCrypto amount paid out to the user’s crypto wallet in Buy crypto flow.

Fiat amount paid out to the user’s fiat account (e.g. credit card) in Sell crypto flow.
Same as amountFrom but handled second.
transactionFlowoptionalDefines the transaction flow type: buy or sell crypto. Possible values: buyCrypto (by default), sellCrypto.
partnerUserIdoptionalAllows to pass an identifier of the customer in the partner's system. partnerUserId is then returned in webhook notifications associated with a certain user.
localeoptionalDefines the preferable UI language schema.Possible values: English en (by default), German de, Russian ru, Italian it, French fr, Spanish es, Portuguese pt, Korean ko
successReturnURLoptionalAllows to set the URL to which a user is redirected after completing a transaction in the widget.If the successReturnURL is specified, the Back to merchant button is displayed on the Transaction completed final screen in the widget. On clicking on the button, the user is redirected to this URL in the same browser tab.
It should be encoded.
failureReturnURLoptionalAllows to set the URL to which a user is redirected after getting a transaction rejected in the widget. If the failureReturnURLs specified, the Back to merchant button is displayed on the Transaction rejected/canceled final screen in the widget. On clicking on the button, the user is redirected to this URL in the same browser tab.
Should be encoded.
canCloseoptionalAllows to hide the Close widget icon on UI. Set to false to hide the Close icon.
Is used as a condition for displaying the close widget button.

1. Widget is opened in an iframe: - canClose is not passed. result: close button is visible- canClose is passed with value true. result: close button is visible
-canClose is passed with value false. result: close button is not visible2. Widget is opened in same tab with redirect OR new tab: - canClose is not passed. result: close button is not visible- canClose is passed with value true. result: close button is visible- canClose is passed with value false. result: close button is not visible
layoutoptionalThe parameter that provides a “light“ widget layout, works if the “light” value is passed.The default value is default
Possible values - light or default

💱 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}