每个对 XPayLabs 的 API 请求都必须包含一个加密签名。本页详细说明确切的签名算法、每个字段的用途以及常见陷阱。
签名算法
sign 字段按如下方式计算:
其中:
data 是请求体负载(ReqPayload 的 data 字段)
merchant_token 是您配置的密钥令牌
HMAC-SHA256 产生二进制摘要
HEX 将其转换为小写十六进制字符串(64 个字符)
重要:JSON 序列化
data 对象必须序列化为 JSON 且不含多余空格。不同的 JSON 库可能产生不同的输出:
| 库 | 输出 | 有效? |
|---|
JSON.stringify(obj) | {"amount":"100.00","symbol":"USDT","chain":"TRON"} | 是 |
json.dumps(obj, separators=(",",":")) | {"amount":"100.00","symbol":"USDT","chain":"TRON"} | 是 |
json.dumps(obj, indent=2) | 格式化后的带空格/换行 | 否 |
签名仅基于 data 字段计算——而非完整的 ReqPayload 信封。sign、timestamp 和 nonce 字段不参与签名。
请求信封
每个请求必须包含以下四个字段作为 JSON 对象:
语言示例
Node.js
Python
Java
XPayLabs 通过以下方式验证每个请求:
- 从
data 字段和您存储的商家令牌重新计算 HMAC-SHA256 签名。
- 检查计算出的签名是否与提供的
sign 值匹配。
- 验证
timestamp 是否在服务器时钟的 5 分钟以内。
- 确保
nonce 之前未被使用过。
如果任何检查失败,网关返回 401 Unauthorized 响应:
GET 请求签名
对于需要身份认证的 GET 请求(例如 /v1/order/status/{orderId}、/v1/order/pay、/v1/order/getOrderStatus),sign 参数作为查询字符串值传递。签名基于相关参数(通常为 orderId)计算: