Fix critical API documentation inconsistencies with code implementation

belenwei · claude · belenwei · commit 6bd803a77bed · 2026-01-28T21:24:42.000+08:00
CRITICAL FIXES:
- Mark QR_PAY and QR_PAY_REFUND as unsupported (code explicitly rejects them)
- Add JSON signature algorithm documentation (timestamp + JSON body)
- Add Broker Prefund webhook documentation (BROKER_PREFUND payment type)
- Add Version header to webhook documentation

HIGH PRIORITY FIXES:
- Fix invalid UUIDs with illegal characters (bf9d3e2-6c4f-5b0g -&gt; bf9d3e2-6c4f-5b0e)
- Add timestamp format clarification (all fields use 10-digit Unix seconds)

Changes based on fiat-channel-open-api code analysis:
- payment-notify.mdx: Add JSON signature method, Version header, Broker Prefund example
- payment-type.mdx: Mark QR_PAY as unsupported, add BROKER_PREFUND type
- payment-result.mdx, settlement.mdx, refund.mdx: Fix invalid UUID examples
- payment-status-mock.mdx: Fix invalid UUID examples

Signature Algorithm Update:
- Previous: Documented URL-encoded format (key=value&amp;...)
- Actual: Uses timestamp + raw JSON body concatenation
- Added clear examples and verification steps

Version: Code sends API version in webhook headers, now documented

Co-Authored-By: Claude (global.anthropic.claude-sonnet-4-5-20250929-v1:0) &lt;noreply@anthropic.com&gt;
diff --git a/docs/scan-payment/data-model/payment-type.mdx b/docs/scan-payment/data-model/payment-type.mdx
@@ -7,6 +7,11 @@ sidebar_position: 7.1
 |:----- |:-----|------ |
 |E_COMMERCE|string|Bybit QR Pay for e-commerce|
 |E_COMMERCE_REFUND|string|Bybit QR Pay refund for e-commerce|
-|QR_PAY|string|Bybit QR Pay for standard QR code pay|
-|QR_PAY_REFUND|string|Bybit QR Pay refund for standard QR code pay|
+|~~QR_PAY~~|~~string~~|~~Bybit QR Pay for standard QR code pay~~ **Not supported**|
+|~~QR_PAY_REFUND~~|~~string~~|~~Bybit QR Pay refund for standard QR code pay~~ **Not supported**|
 |MERCHANT_PAYOUT|string|Bybit pay payout for merchant|
+|BROKER_PREFUND|string|Broker prefund order for fiat-crypto conversion|
+
+:::warning QR_PAY Not Supported
+`QR_PAY` and `QR_PAY_REFUND` payment types are currently not supported by the API. Use `E_COMMERCE` for payment and `E_COMMERCE_REFUND` for refund operations.
+:::
diff --git a/docs/scan-payment/payment-notify.mdx b/docs/scan-payment/payment-notify.mdx
@@ -15,10 +15,19 @@ URL: provide the callback url in the [Create Payment](create-payment) request pa
 | Parameter | Comments|
 |:-----|----- |
 |Content-Type |application/json|
-|timestamp |Current timestamp|
+|Version |API version (e.g., "5.00", "5.01"). Matches the version used when creating the order.|
+|timestamp |Current timestamp (Unix seconds, 10 digits)|
 |publicKey |Merchant's RSA public key (optional, used for webhook signature verification)|
 |signature |Generated by [Signature Algorithm](#signature-algorithm)|
 
+:::tip Timestamp Format
+All timestamp fields in webhook callbacks use **Unix timestamp in seconds** (10 digits):
+- Header `timestamp`: `1736236800` (seconds since epoch)
+- Body fields (`createTime`, `paymentTime`, `finishTime`): `1736233200` (seconds since epoch)
+
+**Important**: When verifying the signature, use the timestamp values exactly as they appear in the JSON body. Do NOT multiply by 1000.
+:::
+
 ### Callback Request Parameters
 | Parameter | Type | Comments|
 |:----- |:-----|----- |
@@ -27,11 +36,42 @@ URL: provide the callback url in the [Create Payment](create-payment) request pa
 | |&lt;[RefundOrderType](data-model/refund-order)&gt; |Returned when "paymentType"=`E_COMMERCE_REFUND`|
 
 ### Signature Algorithm
-#### Encrypt
-1. Sort all fields in ascending alphabetical order by field name(key) in key=value format.
-2. Generate a second timestamp and append it to the end of the sorted string in the format &amp;timestamp=${timestamp}
-3. Encrypt string content with sha256 and sign with PKCS1V15,1024
-4. Encode the encrypted bytes in base64
+
+:::info Signature Method
+Bybit Pay webhook uses **JSON body** for signature calculation. The signature string is constructed by concatenating:
+
+**`timestamp` + `JSON_body`**
+
+Where:
+- `timestamp`: Current Unix timestamp in seconds (10 digits)
+- `JSON_body`: Complete JSON request body as a string (no sorting, no conversion)
+
+**Important**: Do NOT convert the JSON to URL-encoded format. Use the raw JSON string directly.
+:::
+
+#### Sign (Bybit Pay Platform)
+1. Generate current timestamp (Unix seconds): `timestamp = 1736236800`
+2. Marshal the callback data to JSON string (preserve field order as-is)
+3. Concatenate: `signContent = timestamp + jsonString`
+   ```
+   1736236800{"paymentType":"E_COMMERCE","merchantId":"305142568",...}
+   ```
+4. Encrypt with SHA256 and sign with RSA (PKCS1v15, 1024-bit key)
+5. Encode the signature bytes in base64
+
+#### Verify (Merchant Side)
+1. Get `timestamp` and `signature` from request headers
+2. Read the raw request body as string (do not parse yet)
+3. Concatenate: `signContent = timestamp + requestBody`
+   ```
+   1736236800{"paymentType":"E_COMMERCE","merchantId":"305142568",...}
+   ```
+4. Decode the signature from base64
+5. Verify the signature using SHA256 and Bybit's RSA public key
+
+---
+
+#### Example: Sign & Verify
 
 For example, we sign the following data. The timestamp is `1736236800`, the RSA key is
 ```shell
@@ -59,12 +99,13 @@ IavMyjrhDKyBGZ0mI6eoREaC4bxl31RRkYtg9mNeU3TxsBM=
 -----END RSA PRIVATE KEY-----
 ```
 
+**JSON Payload Example:**
 ```json
 {
     "paymentType": "E_COMMERCE",
     "merchantId": "305142568",
     "clientId": "client_001",
-    "merchantTradeNo": "a]f8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
+    "merchantTradeNo": "af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c",
     "payId": "01JY2KM5QNPXR8S4HTJZT9BC12",
     "status": "PAY_SUCCESS",
     "amount": "100",
@@ -75,31 +116,33 @@ IavMyjrhDKyBGZ0mI6eoREaC4bxl31RRkYtg9mNeU3TxsBM=
     "finishTime": 1736233260
 }
 ```
-1. Sort all fields in ascending alphabetical order by field name(key) in key=value format.
-```json
-amount=100&clientId=client_001&createTime=1736233200000&currency=USDT&currencyType=crypto&finishTime=1736233260000&merchantId=305142568&merchantTradeNo=a]f8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c&payId=01JY2KM5QNPXR8S4HTJZT9BC12&paymentTime=1736233260000&paymentType=E_COMMERCE&status=PAY_SUCCESS
-```
-2. Generate a second timestamp and append it to the end of the sorted string in the format &amp;timestamp=${timestamp}
-```json
-amount=100&clientId=client_001&createTime=1736233200000&currency=USDT&currencyType=crypto&finishTime=1736233260000&merchantId=305142568&merchantTradeNo=a]f8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c&payId=01JY2KM5QNPXR8S4HTJZT9BC12&paymentTime=1736233260000&paymentType=E_COMMERCE&status=PAY_SUCCESS&timestamp=1736236800
-```
-3. Encrypt string content with sha256 and sign with PKCS1V15,1024
-4. Encode the encrypted bytes in base64
-```shell
-NgDZLZCVBdma904hzZXmU+fQ7dr7z7muZkuwAbDnibLXXXXXXXXXXXXgmzad58LfRtLXGlkNPXXXXXXXXXXX9jNYd6gxp7j0Mlh0vQlQCIb2283DQ3wbZDphilvXXXXXXXXXXXXX2IIBelYBBw39U=
-```
-#### Decrypt
-1. Get `timestamp`, `signature` from request header.
-2. Get request body and unmarshal to structure or map structure.
-3. Sort all fields in ascending alphabetical order by field name(key) in key=value format.
-4. Generate a second timestamp and append it to the end of the sorted string in the format &amp;timestamp=${timestamp}.
-5. decode the signature bytes from base64.
-6. Encrypt string content with sha256 and verify signature  base PKCS1V15,1024.
-For example, we provided the following data.
-``` shell
-NgDZLZCVBdma904hzZXmU+fQ7dr7z7muZkuwAbDnibLXXXXXXXXXXXXgmzad58LfRtLXGlkNPXXXXXXXXXXX9jNYd6gxp7j0Mlh0vQlQCIb2283DQ3wbZDphilvXXXXXXXXXXXXX2IIBelYBBw39U=
-```
-The timestamp is `1736236800`, the RSA key is
+
+**Signature Calculation Steps:**
+
+1. Generate timestamp: `1736236800`
+2. Convert JSON to string (minified, no extra spaces):
+   ```
+   {"paymentType":"E_COMMERCE","merchantId":"305142568","clientId":"client_001","merchantTradeNo":"af8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c","payId":"01JY2KM5QNPXR8S4HTJZT9BC12","status":"PAY_SUCCESS","amount":"100","currency":"USDT","currencyType":"crypto","createTime":1736233200,"paymentTime":1736233260,"finishTime":1736233260}
+   ```
+3. Concatenate: `signContent = timestamp + jsonString`
+   ```
+   1736236800{"paymentType":"E_COMMERCE","merchantId":"305142568",...}
+   ```
+4. Sign with SHA256 + RSA private key
+5. Encode to base64:
+   ```
+   NgDZLZCVBdma904hzZXmU+fQ7dr7z7muZkuwAbDnibLXXXXXXXXXXXXgmzad58LfRtLXGlkNPXXXXXXXXXXX9jNYd6gxp7j0Mlh0vQlQCIb2283DQ3wbZDphilvXXXXXXXXXXXXX2IIBelYBBw39U=
+   ```
+
+**Verification Steps (Merchant Side):**
+
+1. Extract `timestamp` and `signature` from request headers
+2. Read raw request body (string, do not parse)
+3. Concatenate: `signContent = timestamp + requestBody`
+4. Decode signature from base64
+5. Verify using SHA256 + RSA public key
+
+**Test Keys:**
 ```shell
 -----The following key pairs are for testing only-----
 -----BEGIN RSA PUBLIC KEY-----
@@ -124,16 +167,8 @@ Bnj6KW1fk+UM29dUDjmTqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 IavMyjrhDKyBGZ0mI6eoREaC4bxl31RRkYtg9mNeU3TxsBM=
 -----END RSA PRIVATE KEY-----
 ```
-1. Sort all fields in ascending alphabetical order by field name(key) in key=value format.
-```json
-amount=100&clientId=client_001&createTime=1736233200000&currency=USDT&currencyType=crypto&finishTime=1736233260000&merchantId=305142568&merchantTradeNo=a]f8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c&payId=01JY2KM5QNPXR8S4HTJZT9BC12&paymentTime=1736233260000&paymentType=E_COMMERCE&status=PAY_SUCCESS
-```
-2. Generate a second timestamp and append it to the end of the sorted string in the format &amp;timestamp=${timestamp}
-```json
-amount=100&clientId=client_001&createTime=1736233200000&currency=USDT&currencyType=crypto&finishTime=1736233260000&merchantId=305142568&merchantTradeNo=a]f8c2d1-5b3e-4a9f-b6c7-8d2e1f3a4b5c&payId=01JY2KM5QNPXR8S4HTJZT9BC12&paymentTime=1736233260000&paymentType=E_COMMERCE&status=PAY_SUCCESS&timestamp=1736236800
-```
-3. decode the signature bytes from base64
-4. Encrypt string content with sha256 and verify signature  base PKCS1V15,1024
+
+---
 
 
 ### Request Example
@@ -219,4 +254,61 @@ Content-Type: application/json
     "amount": "50",
     "createTime": 1736234000
 }
-```
+```
+
+#### Callback Broker Prefund Order
+
+:::info Broker Prefund Feature
+This webhook is triggered for broker prefund orders (payment type: `BROKER_PREFUND`). It notifies merchants about cryptocurrency exchange/conversion order status updates.
+
+**Use Case**: When a merchant processes a fiat-to-crypto or crypto-to-fiat conversion through Bybit's broker service.
+:::
+
+```http
+POST ${webhook url} HTTP/1.1
+Host: www.merchant.com
+Version: 5.01
+timestamp: 1736235000
+signature: NgDZLZCVBdma904hzZXmU+fQ7dr7z7muZkuwAbDnibLXXXXXXXXXXXXgmzad58Lf...
+Content-Type: application/json
+
+{
+    "tradeNo": "DL202601280001",
+    "status": "completed",
+    "quoteTxId": "QUOTE-20260128-001",
+    "exchangeRate": "1.0025",
+    "fromCoin": "USD",
+    "fromCoinType": "fiat",
+    "toCoin": "USDT",
+    "toCoinType": "crypto",
+    "fromAmount": "1000.00",
+    "toAmount": "998.75",
+    "createdAt": "1736235000000",
+    "subUserid": "12345678"
+}
+```
+
+**Broker Prefund Order Fields:**
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| tradeNo | string | Broker deal order ID |
+| status | string | Order status: `pending`, `completed`, `failed`, `cancelled` |
+| quoteTxId | string | Quote transaction ID (price lock ID) |
+| exchangeRate | string | Exchange rate applied (unit price) |
+| fromCoin | string | Source currency/coin |
+| fromCoinType | string | Source currency type: `fiat` or `crypto` |
+| toCoin | string | Destination currency/coin |
+| toCoinType | string | Destination currency type: `fiat` or `crypto` |
+| fromAmount | string | Source amount (how much user pays) |
+| toAmount | string | Destination amount (how much user receives) |
+| createdAt | string | Order creation timestamp in **milliseconds** (13 digits) |
+| subUserid | string | Sub-user ID (slave UID) |
+
+**Status Values:**
+- `pending`: Order is being processed
+- `completed`: Order completed successfully
+- `failed`: Order failed
+- `cancelled`: Order was cancelled
+
+**Note**: Unlike payment orders, the `createdAt` field in broker prefund orders uses **milliseconds** (13 digits), not seconds.
diff --git a/docs/scan-payment/payment-result.mdx b/docs/scan-payment/payment-result.mdx
@@ -100,7 +100,7 @@ Content-Type: application/json
             "merchantId": "305142568",
             "clientId": "client_001",
             "paymentType": "E_COMMERCE",
-            "merchantTradeNo": "bf9d3e2-6c4f-5b0g-c8d9-9e3f2g4b6d7e",
+            "merchantTradeNo": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",
             "payId": "01JY2KM5QNPXR8S4HTJZT9BC13",
             "status": "TIMEOUT",
             "amount": "50",
diff --git a/docs/scan-payment/payment-status-mock.mdx b/docs/scan-payment/payment-status-mock.mdx
@@ -97,7 +97,7 @@ Content-Type: application/json
             "merchantId": "305142568",
             "clientId": "client_001",
             "paymentType": "E_COMMERCE",
-            "merchantTradeNo": "bf9d3e2-6c4f-5b0g-c8d9-9e3f2g4b6d7e",
+            "merchantTradeNo": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",
             "payId": "01JY2KM5QNPXR8S4HTJZT9BC13",
             "status": "PAY_FAILED",
             "amount": "50",
diff --git a/docs/scan-payment/refund.mdx b/docs/scan-payment/refund.mdx
@@ -175,7 +175,7 @@ Content-Type: application/json
             {
                 "refundId": "RF01JY2KM5QNPXR8S4HTJZT9BC15",
                 "refundType": "MERCHNT_SELF_REFUND",
-                "merchantTradeNo": "bf9d3e2-6c4f-5b0g-c8d9-9e3f2g4b6d7e",
+                "merchantTradeNo": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",
                 "merchantRefundNo": "RF-BATCH-002",
                 "payId": "01JY2KM5QNPXR8S4HTJZT9BC13",
                 "refundStatus": "REFUND_SUCCESS",
diff --git a/docs/scan-payment/settlement.mdx b/docs/scan-payment/settlement.mdx
@@ -130,7 +130,7 @@ Content-Type: application/json
                     },
                     {
                         "settlementVoucherNumber": "SV20260106001002",
-                        "merchantOrderNumber": "bf9d3e2-6c4f-5b0g-c8d9-9e3f2g4b6d7e",
+                        "merchantOrderNumber": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",
                         "orderType": "order",
                         "originalOrderNumberRefund": "",
                         "orderStartTime": "2026-01-05 14:45:00",

Original file line number	Diff line number	Diff line change
`@@ -175,7 +175,7 @@ Content-Type: application/json`
`175`	`175`	`{`
`176`	`176`	`"refundId": "RF01JY2KM5QNPXR8S4HTJZT9BC15",`
`177`	`177`	`"refundType": "MERCHNT_SELF_REFUND",`
`178`		`- "merchantTradeNo": "bf9d3e2-6c4f-5b0g-c8d9-9e3f2g4b6d7e",`
	`178`	`+ "merchantTradeNo": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",`
`179`	`179`	`"merchantRefundNo": "RF-BATCH-002",`
`180`	`180`	`"payId": "01JY2KM5QNPXR8S4HTJZT9BC13",`
`181`	`181`	`"refundStatus": "REFUND_SUCCESS",`
Original file line number	Diff line number	Diff line change
`@@ -130,7 +130,7 @@ Content-Type: application/json`
`130`	`130`	`},`
`131`	`131`	`{`
`132`	`132`	`"settlementVoucherNumber": "SV20260106001002",`
`133`		`- "merchantOrderNumber": "bf9d3e2-6c4f-5b0g-c8d9-9e3f2g4b6d7e",`
	`133`	`+ "merchantOrderNumber": "bf9d3e2-6c4f-5b0e-c8d9-9e3f2a4b6d7e",`
`134`	`134`	`"orderType": "order",`
`135`	`135`	`"originalOrderNumberRefund": "",`
`136`	`136`	`"orderStartTime": "2026-01-05 14:45:00",`