Skip to main content

Create Payment

HTTP Request

POST /v5/bybitpay/create_pay

Request Parameters

ParameterRequiredTypeComments
merchantIdtruestringOnboarding merchant UID
merchantNamefalsestringIf not filled in, we will show users the name of your company doing KYB on the Bybit platform
clientIdfalsestringMerchant client ID
paymentTypetruestringPayment type
customerfalse<CustomerType>Customer info
merchantTradeNotruestringMerchant order number
goodstruearray<GoodType>Product description
orderAmounttruestringOrder amount
currencytruestringOrder currency (uppercase, e.g., EUR, USD, USDT)
currencyTypetruestringCurrency type (fiat or crypto)
successUrlfalsestringURL to return after successful payment (max 256 characters)
failedUrlfalsestringURL to return after failed payment (max 256 characters)
webhookUrlfalsestringAPI URL to call when order is successful or failed (max 256 characters)
orderExpireTimefalseint64Order expiration time in UTC timestamp (second precision), default is 1 hour, max is 1 hour
envtrue<EnvType>Transaction source
riskInfofalse<RiskInfoType>Risk info for order pay

Response Parameters

ParameterTypeComments
payIdstringPay-order ID created successfully
terminalTypestringTransaction source (APP, WEB, WAP, MINIAPP, OTHERS)
expireTimenumberOrder expiration time in UTC timestamp (second precision)
checkoutLinkstringUnified checkout link in Bybit, redirect for payment
qrContentstringQR 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: api.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1739178959616
X-BAPI-RECV-WINDOW: 50000
Content-Type: application/json

{
"currency": "USDT",
"currencyType": "crypto",
"env": {
"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",
"device": "xxde",
"ip": "127.0.0.1",
"terminalType": "APP"
},
"failedUrl": "",
"customer":{
"externalUserId": "test@gmail.com",
"userName": "john li",
"registerTime": "1739178959",
"kycCountry": "AUS"
},
"goods": [
{
"shoppingName": "test good",
"mccCode": "1520",
"goodsName": "test",
"goodsDetail": "test"
}
],
"merchantId": "305142568",
"merchantName": "uquid",
"merchantTradeNo": "841e4ba2-c7ec-40b1-a071-a2a45de7bd00",
"orderAmount": "100",
"orderExpireTime": 0,
"paymentType": "E_COMMERCE",
"successUrl": "",
"webhookUrl": ""
}

Response Example

{
"retCode": 100000,
"retMsg": "success",
"result": {
"payId": "01JN6AZVEMAC8H9SED6JES3QH8",
"terminalType": "APP",
"expireTime": 1740751953,
"checkoutLink": "",
"qrContent": "data:image/png;base64,/9j/2wCEAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UXXXXXXXXQAUUUUAFFFFABRRRQAUUUUAf/Z",
"order": {
"merchantId": "305142568",
"clientId": "",
"paymentType": "E_COMMERCE",
"merchantTradeNo": "841e4ba2-c7ec-40b1-a071-a2a45de7bd00",
"payId": "01JN6AZVEMAC8H9SED6JES3QH8",
"status": "INITIAL",
"amount": "100",
"currency": "USDT",
"currencyType": "crypto",
"createTime": 1740748353,
"paymentTime": 0,
"finishTime": 0,
"refundOrders": []
}
}
}