授权

受保护的 API 方法需要使用 HMAC-SHA256 签名进行授权。

Required headers

每个请求必须包含三个必需请求头：

X-Timestamp
Unix 时间戳（秒）
X-Signature
hex 格式的 HMAC-SHA256 请求签名
X-Client-Id
您的商户 ID

Signature generation

签名基于 timestamp 和请求体生成。

格式：

{timestamp}.{canonicalBody}

Format description

timestamp
当前 Unix 时间（秒）
canonicalBody
转换为规范格式的 JSON 请求体

签名算法：

  • 获取当前 Unix 时间（秒）
  • 获取请求体
  • 将 JSON 转换为 canonical 格式
  • 构建字符串：timestamp + "." + canonicalBody
  • 使用 api_secret 通过 HMAC-SHA256 签名该字符串
  • 在请求头中传递 timestamp 和签名

重要要求：

  • api_secret 不得在请求中传输
  • api_secret 只能存储在商户服务器端
  • 每个请求都必须单独计算签名
  • X-Timestamp 必须与生成签名的时间一致
  • 发送到 API 的请求体必须与计算签名时使用的请求体完全一致
  • 无请求体的请求签名字符串格式为：{timestamp}

示例：

Authorization errors

401 Invalid X-Timestamp

{
  "status": 401,
  "message": "Invalid X-Timestamp"
}

401 Expired X-Timestamp

{
  "status": 401,
  "message": "Expired X-Timestamp"
}

401 Invalid X-Signature

{
  "status": 401,
  "message": "Invalid X-Signature"
}

401 Invalid token

{
  "status": 401,
  "message": "Invalid token"
}

401 Merchant secret not configured

{
  "status": 401,
  "message": "Merchant secret not configured"
}

500 Internal Server Error

{
  "status": 500,
  "message": "Internal Server Error"
}