Create Payment

HTTP Request

POST /v5/bybitpay/create_pay

E-Commerce Request

Request Parameters

Parameter	Required	Type	Comments
merchantId	true	string	Onboarding merchant UID
merchantName	false	string	If not filled in, we will show users the name of your company doing KYB on the Bybit platform
clientId	false	string	Merchant client ID
paymentType	true	string	Payment type
customer	false	<CustomerType>	Customer info
merchantTradeNo	true	string	Merchant order number
quotationId	false	string	Return result quotationId to create order
goods	true	array<GoodType>	Product description
orderAmount	true	string	Order amount
currency	true	string	Order currency (uppercase, e.g., `EUR`, `USD`, `USDT`)
currencyType	true	string	Currency type (`fiat` or `crypto`)
successUrl	true	string	URL to return after successful payment (max 256 characters)
failedUrl	true	string	URL to return after failed payment (max 256 characters)
webhookUrl	true	string	API URL to call when order is successful or failed (max 256 characters)
orderExpireTime	false	int64	Order expiration time in UTC timestamp (second precision), default is 1 hour, max is 1 hour
env	true	<EnvType>	Transaction source
riskInfo	false	<RiskInfoType>	Risk info for order pay
remark	false	string	Payment remark, max 50 characters
chainAddress	false	string	Chain address
chainType	false	string	The receiver's chain type (BSC/TRX/ARBI/LTC/SOL/ETH/TON/APTOS)

Request Example

POST /v5/bybitpay/create_pay HTTP/1.1
Host: api2.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json

{
    "merchantId": "305142568",
    "merchantName": "Digital Store",
    "clientId": "client_001",
    "paymentType": "E_COMMERCE",
    "merchantTradeNo": "af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
    "orderAmount": "100",
    "currency": "USDT",
    "currencyType": "crypto",
    "successUrl": "https://www.merchant.com/success",
    "failedUrl": "https://www.merchant.com/failed",
    "webhookUrl": "https://www.merchant.com/webhook/bybitpay",
    "orderExpireTime": 1736236800,
    "remark": "Order for digital goods",
    "customer": {
        "externalUserId": "user123@merchant.com",
        "userName": "John Doe",
        "registerTime": 1704067200,
        "kycCountry": "USA",
        "remarks": "VIP customer"
    },
    "goods": [
        {
            "shoppingName": "Digital Store",
            "mccCode": "5816",
            "goodsName": "Premium Subscription",
            "goodsDetail": "Monthly subscription for premium features"
        }
    ],
    "env": {
        "terminalType": "WEB",
        "device": "Mozilla/5.0 compatible browser",
        "browserVersion": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "ip": "192.168.1.100"
    },
    "riskInfo": {
        "terminalType": "WEB"
    },
    "chainAddress": "",
    "chainType": ""
}

Auth Request

Auth reuses the Payment Creation endpoint. Set paymentType to E_COMMERCE and use paymentMethod = AUTH to distinguish this scenario from the existing E-Commerce Payment flow. Fields not listed below follow the common Payment Creation definition above.

Field Name	Type	Required	Description
`paymentType`	string	Yes	Must be `E_COMMERCE`.
`paymentMethod`	string	Yes	Must be `AUTH`.
`orderAmount`	string	Yes	Must be exactly `0`. Auth does not initiate a payment or asset transfer.
`goods`	array<`Good Type`>	No	Optional for Auth. If provided, each item follows the existing validation rules.
`env`	`Env Type`	Yes	Transaction Source. The validation rules are the same as the existing E-Commerce Payment flow.
`riskInfo`	`RiskInfo`	No	Risk info for order pay
`customer`	`Customer Type`	No	Customer info
`quotationId`	string	No	Not used in current use case
`chainAddress`	string	No	Not used in current use case
`chainType`	string	No	Not used in current use case

orderExpireTime is the authorization confirmation deadline. It remains a UTC Unix timestamp in seconds, defaults to one hour, and cannot exceed one hour from order creation.

Request demo

{
  "merchantId": "305142568",
  "merchantName": "Example Merchant",
  "merchantTradeNo": "auth-20261005-000001",
  "paymentType": "E_COMMERCE",
  "paymentMethod": "AUTH",
  "orderAmount": "0",
  "currency": "USDT",
  "currencyType": "crypto",
  "successUrl": "https://merchant.example.com/auth/success",
  "failedUrl": "https://merchant.example.com/auth/failed",
  "webhookUrl": "https://merchant.example.com/webhook/bybitpay",
  "orderExpireTime": 1791180000,
  "env": {
    "browserVersion": "Mozilla/5.0",
    "device": "merchant-device-id",
    "ip": "127.0.0.1",
    "terminalType": "APP"
  }
}

Common Response

The response structure is shared by E-Commerce and Auth. For Auth, result.order.amount is 0 and result.order.authStatus is initially PENDING.

Response Parameters

Parameter	Type	Comments
payId	string	Pay-order ID created successfully
terminalType	string	Transaction source (APP, WEB, WAP, MINIAPP, OTHERS)
expireTime	number	Order expiration time in UTC timestamp (second precision)
checkoutLink	string	Unified checkout link in Bybit, redirect for payment
qrContent	string	QR code content (base64 Image, valid for 1 hour), developers generate QR image
order	<PayOrderType>	Bybit pay order detail
customer	<CustomerType>	Customer info

Response Example

{
    "retCode": 100000,
    "retMsg": "success",
    "result": {
        "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
        "terminalType": "WEB",
        "expireTime": 1736236800,
        "checkoutLink": "bybitapp://open/route?targetUrl=by-mini%3A%2F%2Fpay%2FscanResult%3ForderNo%3D01JY2KM5QNPXR8S4HTJZT9BC12",
        "qrContent": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAIAAAAP3aGbAAC...",
        "order": {
            "merchantId": "305142568",
            "clientId": "client_001",
            "paymentType": "E_COMMERCE",
            "merchantTradeNo": "af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
            "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
            "status": "INIT",
            "amount": "100",
            "currency": "USDT",
            "currencyType": "crypto",
            "createTime": 1736233200,
            "paymentTime": 0,
            "finishTime": 0,
            "refundOrders": [],
            "remark": "Order for digital goods",
            "chainAddress": "",
            "chainType": ""
        },
        "customer": {
            "uid": "104326789",
            "externalUserId": "user123@merchant.com",
            "userName": "John Doe",
            "registerTime": 1704067200,
            "kycCountry": "USA",
            "remarks": "VIP customer"
        }
    }
}

HTTP Request​

E-Commerce Request​

Request Parameters​

Request Example​

Auth Request​

Request demo​

Common Response​

Response Parameters​

Response Example​