Web: API-Based Integration
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 requestIdwhen 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 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. |
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 guideSetting correct iframe permissions and configuration to ensure proper functionality (e.g., payments, KYC)
→ See iframe configuration
Updated 26 days ago