Skip to main content

签名验证说明

为确保 API 调用的安全性，所有请求都需要进行签名验证。平台当前签名算法为 HMAC-SHA256，摘要结果使用 Base64 编码输出。

签名步骤​

  1. 根据接口签名字段白名单取值，不参与签名的字段不要放入签名串。
  2. 移除值为 null 的字段。
  3. 移除空字符串字段。
  4. 将剩余参数按照参数名 ASCII 码从小到大排序。
  5. 将参数按 参数名=参数值 的格式拼接成字符串，并用 & 连接。
  6. 使用 HMAC-SHA256 算法对拼接字符串进行加密。
  7. 将摘要结果做 Base64 编码，得到签名值。

在线签名工具​

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

签名示例​

原始请求参数​

{
  "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://api.example.com/notify&timestamp=1642233600000

3. 生成签名​

const crypto = require('crypto');
const message = 'amount=1000000&currency=VND&merchantOrderNo=ORDER_123456&notificationUrl=https://api.example.com/notify&timestamp=1642233600000';
const signature = crypto
  .createHmac('sha256', 'your_secret_key')
  .update(message)
  .digest('base64');

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: BASE64_HMAC_SHA256_SIGN' \
-d '{
  "merchantOrderNo": "ORDER_123456",
  "amount": 1000000,
  "currency": "VND",
  "timestamp": "1642233600000"
}'

注意事项​

  1. 请求头必须包含 X-API-KEY 和 X-API-SIGN
  2. 时间戳必须是当前时间，误差不能超过 5 分钟
  3. 参数值为 null 或空字符串时不参与签名
  4. sign 字段本身不参与签名
  5. 请妥善保管您的 Secret Key，不要泄露给他人

代码示例​

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