---
title: "POST /v3/request"
method: POST
path: "/v3/request"
tags: ["Request"]
---

# POST /v3/request

`POST /v3/request`

Create request with userIp required

## Headers

- `X-Request-Signature` string

## Request body

- object
  - `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, nullable — The transaction ID in your system to associate the request with.
  - `quoteId` string, uuid4, nullable — 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, nullable — 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, nullable — Refund wallet details. Optional for all flows
  - `email` string, email, nullable — 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, nullable — The shared KYC token from Sumsub. If specified, user will not be required to go through the KYC process during the Widget journey.
  - `locale` 'en' | 'ru' | 'es' | 'it' | 'fr' | 'de' | 'pt' | 'ko' — 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, nullable — 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.
    - `firstName` string — User's first name
    - `lastName` string — User's last name
    - `dateOfBirth` string — User's date of birth. Date only (ISO 8601 format)
    - `country` string — 2-symbol ISO country code
    - `state` string, nullable — 2-symbol state code. Required if country equals to 'US'
    - `address` string, nullable — User's address line
    - `city` string, nullable — User's city of residence
    - `zip` string, nullable — User's postal code
    - `phone` string, nullable — User's phone number
    - `documentType` 'PASSPORT' | 'DRIVERS_LICENCE' | 'IDENTITY_CARD' | 'RESIDENCE_PERMIT', nullable — User's identification document type
    - `documentNumber` string, nullable — User's identification document number
  - `paymentMethod` string, nullable — Set payment method.
  - `payoutMethod` string, nullable — Set payout method.
  - `flow` 'buyCrypto' | 'sellCrypto' | 'swapCrypto', nullable — Set transaction flow.
  - `cryptoPaymentMethod` 'manual' | 'partner_controlled_with_redirect' | 'partner_controlled_with_sdk_event' — 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".
  - `depositCallbackUrl` string, 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, nullable — Textual description of the item being sold.
  - `merchantCompanyName` string, nullable — Name of the merchant as it will appear on the payment details screen.
  - `userIp` string — user IP address (ipv4 or ipv6), private IPs are not allowed

## Response `201`

A request item successfully created.

- object
  - `requestId` string, uuid4 — ID of the purchase used as an argument required for Widget initialization
  - `oneTimeToken` string, nullable — One-time authentication token used as an argument on Widget initialization for automatic login of the customer

## Other responses

- `401` — API key is missing
- `403` — Invalid API key or access disabled
- `404` — Quote for request not found
- `422` — Validation error
- `429` — Too many requests
- `451` — Service is unavailable due to local regulatory requirements
- `503` — Maintenance status

---

[API](https://skmtc.dev/payb/apis/widget.md) · [All operations](https://skmtc.dev/payb/apis/widget/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payb/widget/revisions/2c2cf39656c5/schema)