Web: Direct URL standalone integration

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

1: Get a partner ID

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 widget via 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 ID for sandbox and production environments will be different.

2: Build integration

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

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

  • To start the widget with 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 crypto currency 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 crypto currency 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 spent for Buy crypto purchase order.

Crypto amount that the user is going to withdraw in Sell crypto flow.
Handled first. When exists and 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 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 successfully completing a transaction in widget.If the successReturnURL is specified, the Back to merchant button is displayed on the Transaction completed final screen in the widget. On click on the button, the user is redirected to this URL in the same browser tab.
Should be encoded.
failureReturnURLoptionalAllows to set the URL to which a user is redirected after getting a transaction rejected in widget. If the failureReturnURLs specified, the Back to merchant button is displayed on the Transaction rejected/cancelled final screen in the widget. On click 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.