/v2/request

post

https://widget-api.sandbox.paybis.com/v2/request

Payment request initiation method

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

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 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",

  // 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
}

Body Params

partnerUserId

string

The customers unique ID in your system in order to link the request to the existing user’s account or to create a new one in Paybis system. Use the same ID for each request from the same customer to avoid duplicates.

partnerTransactionId

string | null

The transaction ID in your system to associate the request with.

quoteId

string | null

The quote ID. If provided Widget will start with predefined amount and crypto. Otherwise user will be able to specify amount in Widget and choose desired cryptocurrency for purchase.

cryptoWalletAddress

object | null

Payout wallet details. Optional for buy crypto flow and required for swap crypto flow. Allowed or disallowed by the allow_pass_wallet setting.

cryptoWalletAddressForRefund

object | null

Refund wallet details. Optional for all flows

string | null

The customers email address. If specified, user will not be asked to enter his email during the Widget journey. Pay attention email must be matched with partnerUserId for all upcoming requests, unique user on Paybis side is identified by a combination of partnerUserId + email.

applicantSumsubToken

string | null

The shared KYC token from Sumsub. If specified, user will not be required to go through the KYC process during the Widget journey.

locale

string

enum

The customer’s preferred locale in ISO alpha-2 format. It defines the language of Widget UI. User will be able to change in Widget Menu.

passwordless

boolean

Set passwordless authentication for the customer.

trustedKyc

boolean

Set trusted KYC flow for the customer.

trustedKycInfo

object | null

Optional. This optional data is utilized as Know Your Customer (KYC)
information to streamline the payment process. It aims to avoid
redundant requests for personal details during payment,
if required by the selected payment method.

paymentMethod

string | null

Set payment method.

payoutMethod

string | null

Set payout method.

flow

string | null

enum

Set transaction flow.

Allowed:

cryptoPaymentMethod

string

enum

Defines how the payment process is handled within the sellCrypto flow. Possible values:

manual: The user is required to manually transfer funds from any wallet app to the destination wallet shown on widget UI.
partner_controlled_with_sdk_event: The user confirms transaction details in the widget, and the partner receives a corresponding SDK event. The partner then obtains the payment details from Paybis and arranges the payment within their own app.
partner_controlled_with_redirect: The user confirms the transaction in the widget and is redirected to the partner's app to complete the payment. The partner obtains the payment details from Paybis. It is required to pass depositCallbackUrl for this option.

If this property is not set for sellCrypto flow, it is assumed to be "manual".

Allowed:

depositCallbackUrl

uri

Used to redirect the user to the deposit page on the partner's site if
the cryptoPaymentMethod is set to "partner_controlled_with_redirect".

If this property is set, but the cryptoPaymentMethod is either set to
"manual" or not set at all, a validation error will be returned.

salesItemDescription

string | null

Textual description of the item being sold.

merchantCompanyName

string | null

Name of the merchant as it will appear on the payment details screen.

Headers

X-Request-Signature

string

Signature to sign the request. For more information see https://docs.payb.is/reference/signing-requests

Responses

401

API key is missing

403

Invalid API key or access disabled

404

Quote for request not found

Request method

Making Requests

Getting a requestId

200A request item successfully created.

422Validation error

503Maintenance status

Getting a `requestId`