This integration is ideal for partners who want to predefine transaction parameters using the Paybis API and initialize the widget with a session ID (requestId).

You can either generate a direct URL to open the widget (via redirect, new tab, or iframe), or use the Paybis Web SDK to open it programmatically within your web application.

Building integration

❗️
To ensure the security of your integration, signature verification is required for all Public and Private API requests.
More details on how to generate the signature.
The widget must be opened from a whitelisted domain. This applies especially when used in a webview. Contact Paybis to register your domain(s).

To build the integration, follow these steps:

Step	Description	Required	Endpoints (server-to-server)
1	Get the list of supported fiat currencies and crypto assets depending on the transaction flow type (Buy/Sell). Not necessary to make this request before every widget initialization — you can cache the response on your side.	⚠️ Optional	GET Currency Pairs Buy, Sell
2	Get the list of available payment/payout methods for the selected currency pair.	⚠️ Optional	GET Payment methods list , GET Payoutmethods list
3	Request a quote from Paybis for a certain amount and currency pair	⚠️ Optional	POST Quote
4	Obtain the `requestId` required to initialize the widget	✅	POST Request
4.1	Passwordless option Obtain the `oneTimeToken` (Sing sign-on case)	⚠️ Optional	—
5	Generate a widget URL using `requestId` (and optionally `oneTimeToken`, `successReturnURL`, etc.), then open the widget via a direct URL or using the Web SDK with one of the available methods: (e.g. `open()`, or `openInEmbed()`).	✅	—

Web: Widget initialization options

✅ Widget via Web SDK (Recommended)

For most use cases, we recommend using the Web SDK, which simplifies integration and ensures all features work out of the box.

The SDK provides multiple methods for opening the widget and supports flexible configuration options.

👉 For full integration details, see the guide:
Learn more in the Web SDK documentation

Direct Link to the Widget

Generate the widget URL using the following format:

https://{domain}/?requestId={requestId}&successReturnURL={urlencodedUrl}&failureReturnURL={urlencodedUrl}

The actual domain and encoded URLs need to be substituted into the placeholders:

domain:
- Sandbox (for testing): widget.sandbox.paybis.com
- Production: widget.paybis.com
requestId: A string in the following format: uuid. For example, a122b998-15a4-4442-8b9e-2add17d59617.
urlencodedUrl: A URL-encoded string for success and failure return URLs.

Supported query parameters:

Parameter	Required	Description	Comment
`requestId`	mandatory	Session ID is required to initialize the widget.	It can be obtained from the POST Request endpoint response. It's important to obtain a new `requestId` per each user transaction. You can track the status of each user transaction by `requestId`when getting Transaction status webhooks.
`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 merchantbutton is displayed on the Transaction completed final screen in the widget. On clicking on the button, the user is redirected to this URL.
`failureReturnURL`	optional	Allows to set the URL to which a user is redirected after getting a transaction rejected/canceled 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.
`oneTimeToken`	optional	A unique token is generated for customer authorization.	One-time authentication token used as an argument on Widget initialization for automatic login of the customer More Single-sign on details
`canClose`	optional	Allows hiding the Close widget icon on the UI.	Set to `false` to hide the Close icon. Is used as a condition for displaying the close widget button. ⚠️ This setting has no effect when the widget is opened via redirect.
`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`

⚠️
If you intialize the widget via a custom iframe (not via the Web SDK)
When using a raw iframe integration, you're responsible for:

Handling widget and Payment Gateway events manually, such as transaction completion or user cancellation
→ View the widget internal events
→ View the Payment Gateway event handling guide

Setting correct iframe permissions and configuration to ensure proper functionality (e.g., payments, KYC)
→ See iframe configuration