Payment Notify

Authentication

Share the IP whitelist with each other;
Bybit Pay will encrypt the callbacks via RSA_SHA256. Partners can provide the public key, sign date put in result head. For details, please see Signature Algorithm

HTTP Request

Method: POST
URL: provide the callback url in the Create Payment request parameter webhookUrl

Parameter	Comments
Content-Type	application/json
timestamp	Current timestamp
signature	Generated by Signature Algorithm

Callback Request Parameters

Parameter	Type	Comments
paymentType	string	Payment type `E_COMMERCE`: Bybit QR Pay for e-commerce `E_COMMERCE_REFUND`: Bybit QR Pay refund for e-commerce
	<PayOrderType>	Retured when "paymentType"=`E_COMMERCE`
	<RefundOrderType>	Returned when "paymentType"=`E_COMMERCE_REFUND`

Signature Algorithm

Encrypt

Sort all fields in ascending alphabetical order by field name(key) in key=value format.
Generate a second timestamp and append it to the end of the sorted string in the format &timestamp=${timestamp}
Encrypt string content with sha256 and sign with PKCS1V15,1024
Encode the encrypted bytes in base64

For example, we sign the following data. The timestamp is 1740541514, the RSA key is

-----The following key pairs are for testing only-----
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAOFSnhqtu40TOtok+yXeB+O76PXb/VAJU4Yih6hViOdSGd7imWmCSZyP
psl3TmXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXf+AxlKYMj8OQ
AgDPmZG1a5ydFrje4PLytC7sUw3GP4TTk8xg6iMHmYPdRDv7AEWdAgMBAAE=
-----END RSA PUBLIC KEY-----

-----BEGIN RSA PRIVATE KEY-----
MIICXwIBAAKBgQDhUp4arbuNEzraJPsl3gfju+j12/1QCVOGIoeoVYjnUhne4plp
gkmcj6bJd05i4VKAfq082AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DI/DkAIAz5mRtWucnRa43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AoGBAIqpeCi83516xw32XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
axzIwyfWTTATWbiCS9sqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
6gOQYu8kzRqCzqvyMNdAHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
e/Gxi7qhuIKz0mvfA/yieXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
3IBIdV/CbwJBAOQcsOPf+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
/5V9zdim+hPq+9cvsqO7dXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
MY4uV8noiqDRf/pvAkyMMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
15eWR4jEoXMIFkd7Onc6tXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Bnj6KW1fk+UM29dUDjmTqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
IavMyjrhDKyBGZ0mI6eoREaC4bxl31RRkYtg9mNeU3TxsBM=
-----END RSA PRIVATE KEY-----

{
    "paymentType": "E_COMMERCE",
    "merchantId": "12",
    "clientId": "xx",
    "merchantTradeNo": "123456",
    "payId": "123456",
    "status": "INIT",
    "amount": "100",
    "currency": "USDT",
    "currencyType": "crypto",
    "createTime": 1740488831,
    "paymentTime": 1740488831,
    "finishTime": 1740488831
}

Sort all fields in ascending alphabetical order by field name(key) in key=value format.

amount=100&clientId=xx&createTime=1740488831000&currency=USDT&currencyType=crypto&finishTime=1740488831000&merchantId=12&merchantTradeNo=123456&payId=123456&paymentTime=1740488831000&paymentType=E_COMMERCE&status=INIT

Generate a second timestamp and append it to the end of the sorted string in the format &timestamp=${timestamp}

amount=100&clientId=xx&createTime=1740488831000&currency=USDT&currencyType=crypto&finishTime=1740488831000&merchantId=12&merchantTradeNo=123456&payId=123456&paymentTime=1740488831000&paymentType=E_COMMERCE&status=INIT&timestamp=1740541514

Encrypt string content with sha256 and sign with PKCS1V15,1024
Encode the encrypted bytes in base64

NgDZLZCVBdma904hzZXmU+fQ7dr7z7muZkuwAbDnibLXXXXXXXXXXXXgmzad58LfRtLXGlkNPXXXXXXXXXXX9jNYd6gxp7j0Mlh0vQlQCIb2283DQ3wbZDphilvXXXXXXXXXXXXX2IIBelYBBw39U=

Decrypt

Get timestamp, signature from request header.
Get request body and unmarshal to structure or map structure.
Sort all fields in ascending alphabetical order by field name(key) in key=value format.
Generate a second timestamp and append it to the end of the sorted string in the format &timestamp=${timestamp}.
decode the signature bytes from base64.
Encrypt string content with sha256 and verify signature base PKCS1V15,1024. For example, we provided the following data.

NgDZLZCVBdma904hzZXmU+fQ7dr7z7muZkuwAbDnibLXXXXXXXXXXXXgmzad58LfRtLXGlkNPXXXXXXXXXXX9jNYd6gxp7j0Mlh0vQlQCIb2283DQ3wbZDphilvXXXXXXXXXXXXX2IIBelYBBw39U=

The timestamp is 1740541514, the RSA key is

-----The following key pairs are for testing only-----
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAOFSnhqtu40TOtok+yXeB+O76PXb/VAJU4Yih6hViOdSGd7imWmCSZyP
psl3TmXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXf+AxlKYMj8OQ
AgDPmZG1a5ydFrje4PLytC7sUw3GP4TTk8xg6iMHmYPdRDv7AEWdAgMBAAE=
-----END RSA PUBLIC KEY-----

-----BEGIN RSA PRIVATE KEY-----
MIICXwIBAAKBgQDhUp4arbuNEzraJPsl3gfju+j12/1QCVOGIoeoVYjnUhne4plp
gkmcj6bJd05i4VKAfq082AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DI/DkAIAz5mRtWucnRa43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AoGBAIqpeCi83516xw32XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
axzIwyfWTTATWbiCS9sqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
6gOQYu8kzRqCzqvyMNdAHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
e/Gxi7qhuIKz0mvfA/yieXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
3IBIdV/CbwJBAOQcsOPf+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
/5V9zdim+hPq+9cvsqO7dXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
MY4uV8noiqDRf/pvAkyMMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
15eWR4jEoXMIFkd7Onc6tXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Bnj6KW1fk+UM29dUDjmTqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
IavMyjrhDKyBGZ0mI6eoREaC4bxl31RRkYtg9mNeU3TxsBM=
-----END RSA PRIVATE KEY-----

Sort all fields in ascending alphabetical order by field name(key) in key=value format.

amount=100&clientId=xx&createTime=1740488831000&currency=USDT&currencyType=crypto&finishTime=1740488831000&merchantId=12&merchantTradeNo=123456&payId=123456&paymentTime=1740488831000&paymentType=E_COMMERCE&status=INIT

Generate a second timestamp and append it to the end of the sorted string in the format &timestamp=${timestamp}

amount=100&clientId=xx&createTime=1740488831000&currency=USDT&currencyType=crypto&finishTime=1740488831000&merchantId=12&merchantTradeNo=123456&payId=123456&paymentTime=1740488831000&paymentType=E_COMMERCE&status=INIT&timestamp=1740541514

decode the signature bytes from base64
Encrypt string content with sha256 and verify signature base PKCS1V15,1024

Request Example

Callback Pay Order

POST ${webhook url} HTTP/1.1
Host: XXXXX
timestamp: XXXXX
signature: XXXXX
Content-Type: application/json

{
    "paymentType": "E_COMMERCE",
    "merchantId": "12",
    "clientId": "xx",
    "merchantTradeNo": "123456",
    "payId": "123456",
    "status": "INIT",
    "amount": "100",
    "currency": "USDT",
    "currencyType": "crypto",
    "createTime": 1740488831,
    "paymentTime": 1740488831,
    "finishTime": 1740488831
}

Callback Refund Order

POST ${webhook url} HTTP/1.1
Host: XXXXX
timestamp: XXXXX
signature: XXXXX
Content-Type: application/json

{
    "paymentType": "E_COMMERCE_REFUND",
    "refundId": "123",
    "refundType": "MERCHNT_SELF_REFUND",
    "merchantTradeNo": "123456",
    "merchantRefundNo": "123456",
    "payId": "123456",
    "refundStatus": "REFUND_SUCCESS",
    "amount": "17399",
    "createTime": 1740488831
}

Authentication​

HTTP Request​

Header​

Callback Request Parameters​

Signature Algorithm​

Encrypt​

Decrypt​

Request Example​

Callback Pay Order​

Callback Refund Order​