跳转到主要内容

​
认证与安全

本页为 GatePay API 的认证机制、安全协议及签名生成提供完整参考。

​
协议要求

所有 GatePay API 请求必须遵守以下规范：
项目要求
传输协议HTTPS，TLS 1.2 及以上
数据格式JSON（Content-Type: application/json）
签名算法HMAC-SHA512

​
统一响应结构

所有 API 响应均遵循以下统一格式：
字段类型说明
statusstring请求结果：SUCCESS 或 FAIL
codestring错误码（成功时为 null）
labelstring错误名称（成功时为 null）
errorMessagestring错误描述（成功时为 null）
dataobject/array/string/null业务数据
成功响应示例： 
{
  "status": "SUCCESS",
  "code": null,
  "label": null,
  "errorMessage": null,
  "data": {
    "prepayId": "123456789",
    "location": "https://checkout.gateapi.io/...",
    "qrContent": "..."
  }
}
失败响应示例： 
{
  "status": "FAIL",
  "code": "INVALID_REQUEST",
  "label": "Invalid Request",
  "errorMessage": "Missing required field: merchantTradeNo",
  "data": null
}

​
请求头

所有 API 请求必须包含以下请求头：
请求头说明示例
X-GatePay-Certificate-ClientId创建应用后分配的 ClientId，唯一标识你的应用app_abc123def456
X-GatePay-On-Behalf-Of（可选）机构子账户 ID，仅在代理子账户发起请求时传入sub_account_123
X-GatePay-TimestampUTC 毫秒时间戳。时间偏差超过 10 秒的请求将被拒绝1704067200000
X-GatePay-Nonce随机字符串，用于防重放攻击。建议长度 ≤ 32，仅限字母和数字abc123xyz789
X-GatePay-Signature使用 HMAC-SHA512 计算的请求签名，见下方签名生成说明<64位十六进制字符串>

​
签名生成

签名用于保证请求的完整性与真实性。请按以下步骤生成有效签名：

​
签名串格式

签名串由三行组成，每行以换行符（\n）结尾： 
{timestamp}
{nonce}
{body}
  • 第一行： X-GatePay-Timestamp 的值
  • 第二行： X-GatePay-Nonce 的值
  • 第三行： 请求体的原始 JSON 字符串（无请求体时为空字符串）
  • 末尾换行： 第三行之后必须保留一个换行符

​
签名步骤

  1. 生成请求头： 创建 X-GatePay-Timestamp（当前 UTC 毫秒时间戳）和 X-GatePay-Nonce（随机字符串，≤ 32 位字母数字）。
  2. 准备请求体： 取请求体的原始 JSON 字符串。如无请求体（如 GET 请求），则使用空字符串。
  3. 拼接签名串： 按如下格式拼接： 
    {timestamp}\n{nonce}\n{body}\n
  4. 计算 HMAC-SHA512： 以 Payment API Secret 为密钥，对签名串计算 HMAC-SHA512，结果以十六进制字符串输出。
  5. 设置请求头： 将计算结果填入 X-GatePay-Signature 请求头。

​
示例：POST 请求签名

请求信息：
  • 时间戳：1704067200000
  • Nonce：abc123xyz789
  • Payment API Secret：my_secret_key
  • 请求体：{"merchantTradeNo": "order_123", "currency": "USDT", "orderAmount": "100"}
待签名串（哈希前）： 
1704067200000
abc123xyz789
{"merchantTradeNo": "order_123", "currency": "USDT", "orderAmount": "100"}
计算结果（十六进制）： 
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3

​
示例：GET 请求签名

GET 请求无请求体时： 请求信息：
  • 时间戳：1704067200000
  • Nonce：xyz789abc123
  • Payment API Secret：my_secret_key
  • 请求体：（空）
待签名串（哈希前）： 
1704067200000
xyz789abc123

​
回调验签

GatePay 向你的回调地址发送通知时，需使用相同方式验证回调签名：

​
回调请求头

回调请求包含以下用于验签的请求头：
请求头说明
X-GatePay-Timestamp回调发送时的 UTC 时间戳
X-GatePay-Nonce签名生成时使用的随机串
X-GatePay-Signature回调签名

​
验签步骤

  1. 从回调请求头中取出 X-GatePay-Timestamp、X-GatePay-Nonce、X-GatePay-Signature。
  2. 读取回调请求体的原始 JSON 字符串。
  3. 按以下格式拼接签名串： 
    {timestamp}
{nonce}
{body}
  4. 以 Payment API Secret 为密钥计算 HMAC-SHA512。
  5. 将计算结果与 X-GatePay-Signature 对比，一致则验签通过。
  6. 同时校验时间戳是否在合理范围内（如 5 分钟内），防止重放攻击。
重要： 务必先完成验签，再处理回调中的业务数据。

​
签名验证工具

测试和调试签名时，可使用 GatePay 提供的在线工具： GatePay 签名验证工具 该工具支持：
  • 生成测试签名
  • 验证签名正确性
  • 排查签名不匹配问题

​
最佳实践

  • 时间戳校验： 始终验证请求时间戳与服务器当前 UTC 时间的偏差是否在 10 秒以内。
  • Nonce 唯一性： 每次请求使用不同的 Nonce 以防重放攻击。可将已用 Nonce 存入缓存，设置较短的 TTL（如 15 分钟）。
  • 密钥管理： 妥善保管 Payment API Secret 和 Authorization Secret，切勿硬编码在源码中或提交至版本控制系统。
  • 强制 HTTPS： 所有请求必须使用 TLS 1.2 及以上的 HTTPS，拒绝非 HTTPS 请求。
  • 回调安全： 始终先验签再处理，并在回调端点实现幂等检查，防止重复投递导致业务异常。
  • 错误处理： 签名错误时返回 HTTP 400，并记录日志供排查，注意不要在日志中暴露敏感数据。

​
相关文档