重要注意事項

1. 時間戳格式

必須使用毫秒 (13 位 Unix 時間戳)

// ✅ 正確
const timestamp = Date.now().toString(); // "1737554400000"

// ❌ 錯誤
const timestamp = Math.floor(Date.now() / 1000).toString(); // "1737554400" (秒級)

// ✅ 正確
long timestamp = System.currentTimeMillis();  // 1737554400000

// ❌ 錯誤
long timestamp = System.currentTimeMillis() / 1000;  // 1737554400 (秒級)

# ✅ 正確
timestamp = str(int(time.time() * 1000))  # "1737554400000"

# ❌ 錯誤
timestamp = str(int(time.time()))  # "1737554400" (秒級)

2. JSON 格式

必須使用壓縮的 JSON (無空格、無換行)

// ✅ 正確
{"merchantOrderId":"M_ORD_123","orderAmount":{"value":"0.1","currency":"USD"}}

// ❌ 錯誤
{
  "merchantOrderId": "M_ORD_123",
  "orderAmount": {
    "value": "0.1",
    "currency": "USD"
  }
}

為什麼? 請求體的哈希值在客戶端和服務端必須完全一致。多餘的空白字符會導致簽名不匹配。

3. 時間戳容差

• 請求在服務器時間的 ±5 分鐘內有效
• 確保您的服務器時鐘已同步 (使用 NTP)

4. 簽名組成部分順序

簽名組成部分必須嚴格按照以下順序:

1. 時間戳
2. HTTP 方法 (大寫: GET, POST, PUT, DELETE)
3. 路徑 (不包含查詢參數)
4. 請求體哈希或查詢字符串哈希 (如適用)

各組成部分之間使用換行符 (\n) 分隔,不能使用空格或其他字符。

5. 字符編碼

• 所有字符串必須使用 UTF-8 編碼
• Base64 編碼使用標準字符集 (非 URL 安全變體)

相關文檔

• 簽名算法 - 了解簽名計算詳情
• 常見錯誤與解決方案 - 查看常見錯誤處理