The Standalone option is the fastest way to integrate Paybis On/Off Ramp. This integration lets you launch the Paybis widget by building a signed URL – no Paybis API calls are required.

There are two ways to implement Standalone integration:

Direct URL approach — build a URL with required and optional query parameters
Web SDK approach — using one of the methods with required and optional parameters

During onboarding, you’ll be provided with a unique Product UUID (partnerId parameter) and an HMAC key, which must be used for signing the URL (signature parameter). These values must be passed depending on the widget initialization method you choose:

as query parameters when constructing a direct URL
as function parameters when initializing the widget via the Web SDK

❗️
To ensure the security of your integration, all widget URLs must be signed using your HMAC key (signature parameter).
More details on how to generate the signature.

Widget URLs for environments:

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

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

✅Standalone: Widget via Web SDK (Recommended)

In addition to building and opening a signed URL manually, you can launch the Paybis widget using the Web SDK, which is the recommended approach for most web-based applications.

The Web SDK offers:

A simple and flexible way to initialize the widget via JavaScript
Multiple methods to open the widget (popup, new tab, embedded container)
Built-in event handling and automatic updates — everything works out of the box

Instead of passing parameters as query strings, you provide the same values as JavaScript object parameters (e.g. partnerId, currencyCodeFrom, cryptoAddress, etc.).

👉 For full integration details, see the guide:
Standalone Widget Integration via Web SDK →

ℹ️
When using the Web SDK, you must pass the non-encoded signature

Standalone: Direct URL integration

To build the integration, you simply need to open the signed widget URL with your product 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&signature={signature}
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&signature={signature}
to define the transaction flow (buy or sell), use the transactionFlow parameter.

Supported query parameters

Parameter	Required	Description	Validation
`partnerId`	required	Unique 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.
`signature`	required	HMAC signature used to verify the integrity of the widget URL or Web SDK parameters.	HMAC-SHA256 hash of the full query string, generated using your HMAC key. Should be URL-encoded
`cryptoAddress`	optional	User'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.
`currencyCodeFrom`	optional	Fiat 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.
`currencyCodeTo`	optional	Cryptocurrency 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.
`amountFrom`	optional	Amount 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.
`amountTo`	optional	Crypto 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.
`transactionFlow`	optional	Defines the transaction flow type: buy or sell crypto.	Possible values: `buyCrypto` (by default), `sellCrypto`.
`locale`	optional	Defines 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`
`partnerUserId`	optional	Allows to pass an identifier of the customer in the partner's system.	`partnerUserId` is then returned in webhook notifications associated with a certain user.
`successReturnURL`	optional	Allows 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.
`failureReturnURL`	optional	Allows 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.
`canClose`	optional	Allows hiding 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
`layout`	optional	Defines the widget layout.	Use `embed` if the widget is embedded into the page. Use `light` to apply light layout version, use `default` otherwise. Value by default = `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}