Skip to main content

签名验证说明

为确保 API 调用的安全性，所有请求都需要进行签名验证。签名验证使用 HMAC-SHA256 算法。

签名步骤​

  1. 将请求参数按照参数名 ASCII 码从小到大排序（字典序）
  2. 将参数名值对按照 "参数名=urlencode(参数值)" 的格式拼接成字符串，并用 "&" 连接
  3. 使用 HMAC-SHA256 算法，对上述字符串进行加密，得到签名
  4. 将签名结果转换为大写，并放在请求头 X-API-SIGN 中

在线签名工具​

您可以使用下面的工具来生成签名：

签名示例​

原始请求参数​

{
  "merchantOrderNo": "ORDER_123456",
  "amount": 1000000,
  "currency": "VND",
  "notificationUrl": "https://api.example.com/notify",
  "timestamp": "1642233600000"
}

1. 参数排序​

amount=1000000
currency=VND
merchantOrderNo=ORDER_123456
notificationUrl=https://api.example.com/notify
timestamp=1642233600000

2. 参数拼接​

amount=1000000&currency=VND&merchantOrderNo=ORDER_123456&notificationUrl=https%3A%2F%2Fapi.example.com%2Fnotify&timestamp=1642233600000

3. 生成签名​

const crypto = require('crypto');
const message = 'amount=1000000&currency=VND&merchantOrderNo=ORDER_123456&notificationUrl=https%3A%2F%2Fapi.example.com%2Fnotify&timestamp=1642233600000';
const signature = crypto
  .createHmac('sha256', 'your_secret_key')
  .update(message)
  .digest('hex')
  .toUpperCase();

4. 最终请求示例​

curl -X POST 'https://api.example.com/v1/payments' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: your_api_key' \
-H 'X-API-SIGN: 1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF' \
-d '{
  "merchantOrderNo": "ORDER_123456",
  "amount": 1000000,
  "currency": "VND",
  "timestamp": "1642233600000"
}'

注意事项​

  1. 请求头必须包含 X-API-KEY 和 X-API-SIGN
  2. 时间戳必须是当前时间，误差不能超过 5 分钟
  3. 签名结果必须转换为大写
  4. 参数值为空时不参与签名
  5. 请妥善保管您的 Secret Key，不要泄露给他人

代码示例​

请参考签名示例页面，查看不同编程语言的签名实现代码。