Web: Direct URL standalone integration

The direct URL option is the fastest way to integrate Paybis On/Off Ramp. It does not require setting up SDK or calling APIs, and, thus, can be implemented without any changes on the partner's application backend.

📘

For Direct URL standalone integration, use the partner UUID provided by Paybis for authorization instead of the API key.

During your onboarding process, your dedicated integration manager will provide you with your unique partner UUID that must be passed as a query parameter to open the widget via a direct URL. You will also be provided with the API key that you can use to call any of the available widget API methods. This is not required for integrating the widget but could be useful if you need to display quotes or widget capabilities (e.g. supported payment methods and assets) in your application interface.

Widget URLs for environments:

Sandbox for testing: - https://widget.sandbox.paybis.com/?partnerId={partner UUID}
Production: - https://widget.paybis.com/?partnerId={partner UUID}

Note that partner IDs for sandbox and production environments will be different.

2: Build integration

To build the integration, you simply need to open the widget URL with your UUID via redirect to a new window/tab in the browser by clicking on a specific button in your application (e.g. Buy/Sell crypto). Alternatively, the widget can be embedded in an iframe.

To improve user experience, you can pass extra information on widget initialization as additional query parameters:

  • To start the widget with the user's crypto wallet, pass the cryptoAddress, currencyCodeFrom, currencyCodeTo. Example: widget.paybis.com/?partnerId={business account product UUID} & cryptoAddress=32eVTqDWHvDVzAh2rsU6Cd2nRiWVxEyWDD & currencyCodeFrom=EUR & currencyCodeTo=BTC
  • to start the widget with the quote, pass the currencyCodeFrom, currencyCodeTo, amountFrom or amountTo. Example: widget.paybis.com/?partnerId={business account product UUID} & cryptoAddress=32eVTqDWHvDVzAh2rsU6Cd2nRiWVxEyWDD & currencyCodeFrom=EUR & currencyCodeTo=BTC & amountFrom=100
  • to define the transaction flow (buy or sell), use the transactionFlow parameter.
ParameterRequiredDescriptionValidation
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.
currencyCodeFrommandatoryFiat 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.
currencyCodeTomandatoryCryptocurrency 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.
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
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.
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. The user will need to close the browser window to close the widget.
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