Create Payment

HTTP Request

POST /v5/bybitpay/create_pay

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

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

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

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"
        },
        "customer": {
            "uid": "104326789",
            "externalUserId": "user123@merchant.com",
            "userName": "John Doe",
            "registerTime": 1704067200,
            "kycCountry": "USA",
            "remarks": "VIP customer"
        }
    }
}