ℹ️
API /v3/request brings enhanced traceability and security for server-to-server partners while leaving existing widget-based integrations untouched. The centerpiece is the new userIp` field, enabling precise client identification and better abuse mitigation.
Make sure that the IP address** is not passed by the client in the API request body to your server**. You should determine the real client IP on your side and pass it to Paybis.

Request method

This method allows to retrieval the requestId required to run Widget UI via Widget SDK.

❗️
To ensure the security of your integration, signature verification is required for all Private API requests.
More details on how to generate the signature.

🚧
Making Requests
This endpoint must be called from your application's backend.

📘
Getting a requestId

requestId is related to a specific transaction in the Widget. In order to resume an ongoing transaction, your application needs to use the same requestId used to initiate that transaction.

In order to start a new transaction, a new requestId must be obtained and the Paybis Widget should be launched with it.

You can pass the KYC information (see applicantSumsubToken field) when creating requestIdto skip KYC for verified users. Read more in Shared KYC.

Use the Get Payment Methods endpoint to retrieve the list of available methods that can be passed in the paymentMethod field.

Request method provides an option to set the Single sign-on flow for customers that have active session on your end.

In the flow without quote, you can limit the number of cryptocurrencies available on Paybis Widget exchange form in 2 ways:

pass a single cryptowalletaddress object: the cryptocurrency will be locked on the exchange form and the wallet address entry step is skipped in Widget flow.

pass an array of cryptowalletaddress objects: the client will be able to choose crypto from the list you have provided and the related wallet will be used for payout (wallet entry step is skipped).

{
  // The unique identifier for the user in your system. 
  // This helps link the request to the user's existing account or create a new one
  "partnerUserId": "4bb689aa-fd24-46fb-b793-e44c26d24e7a",

  // The preferred language for the user interface of the widget
  "locale": "en",
  //  The end user's IP address (ipv4 or ipv6). ake sure that the IP address is not passed by the client in the API request body to your server.
You should determine the real client IP on your side and pass it to Paybis.
  "userIp": "81.198.59.7"
}

{
  // The unique identifier for the user in your system. 
  // This helps link the request to the user's existing account or create a new one
  "partnerUserId": "4bb689aa-fd24-46fb-b793-e44c26d24e7a",

  // The preferred language for the user interface of the widget
  "locale": "en",

  // The ID of a previously generated quote.
  "quoteId": "99b51850-87c1-4af0-bcf3-ae8684b076c0",

  //  The end user's IP address (ipv4 or ipv6). ake sure that the IP address is not passed by the client in the API request body to your server.
You should determine the real client IP on your side and pass it to Paybis.
  "userIp": "81.198.59.7",

  // Details about the cryptocurrency wallet where the purchased cryptocurrency should be sent
  "cryptoWalletAddress": 
  {
    // The actual address of the cryptocurrency wallet
    "address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",

    // The cryptocurrency code associated with the wallet address. 
    "currencyCode": "BTC-TESTNET" 
  }
}

{
  // The unique identifier for the user in your (the partner's) system. 
  // This helps link the request to the user's existing account or create a new one if needed
  "partnerUserId": "4bb689aa-fd24-46fb-b793-e44c26d24e7a",
  
  // The ID of a previously generated quote.
  // This pre-fills the amount and cryptocurrency selection in widget
  "quoteId": "99b51850-87c1-4af0-bcf3-ae8684b076c0",

  // The user's email address. This might be used for communication or identification purposes.
  "email": "[email protected]", 

  // The preferred language for the user interface (UI) of the widget
  "locale": "en", 

  // Details about the cryptocurrency wallet where the purchased cryptocurrency should be sent
  "cryptoWalletAddress": 
  {
    // The actual address of the cryptocurrency wallet
    "address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",

    // The cryptocurrency code associated with the wallet address. 
    // In this case, it's Bitcoin on the testnet
    "currencyCode": "BTC-TESTNET" 
  },

  // The payment method has chosen to use for the transaction
  "paymentMethod": "credit-card",

  // Enables a passwordless authentication flow for the user
  "passwordless": true,

    //  The end user's IP address (ipv4 or ipv6). Make sure that the IP address is not passed by the client in the API request body to your server.
You should determine the real client IP on your side and pass it to Paybis.
  "userIp": "81.198.59.7"

}

Request method

Making Requests

Getting a requestId

Getting a `requestId`