认证 - Gate Pay DOCS

API 标准与协议

传输与数据格式

项目	规格
传输协议	HTTPS，TLS 1.2 及以上
数据格式	请求体和响应体均为 JSON
Content-Type 请求头	`application/json` (必填)

签名与验签

项目	规格
签名算法	HMAC-SHA512
请求签名	所有商户请求都必须使用 HMAC-SHA512 算法签名。
回调验签	所有 GatePay 回调都必须由商户使用同一算法完成验签。

响应判定

请始终按以下方式判断 API 响应结果：

先检查 HTTP 状态码
再检查响应体中的 status、code、label 和 errorMessage 字段
如果请求成功，则从 data 字段提取业务数据

统一响应结构

所有 GatePay API 响应均遵循以下标准结构:

字段	类型	说明
`status`	字符串	结果状态: `SUCCESS` 表示执行成功; `FAIL` 表示执行失败.
`code`	字符串	错误码 (成功响应中为空).
`label`	字符串	错误名称或标识符 (成功响应中为空).
`errorMessage`	字符串	便于阅读的错误描述 (成功响应中为空).
`data`	对象 / 数组 / 字符串 / null	API 返回的业务数据。失败响应中为空。

请求参数规范

商户订单号 (`merchantTradeNo`)

商户订单号是你为每笔交易分配的唯一标识:

属性	规格
字符集	仅支持 ASCII 半角字符: 字母 (a-z, A-Z), 数字 (0-9), 连字符 (-), 下划线 (_)
最大长度	100 个字符
唯一性	必须在你的商户账户内唯一
重试策略	重试同一笔业务交易时，必须复用原始 `merchantTradeNo`，以确保幂等性

交易金额

属性	规格
数据类型	字符串（以字符串形式表示数值）
小数精度	最多 8 位小数
单笔最小金额	0.0001
单笔最大金额	5,000,000
二维码收款最大金额	10,000 （适用于个人二维码收款）

时间戳格式

属性	规格
格式	Unix 毫秒时间戳（UTC 时区）

请求头与签名

必填请求头

每个 API 请求都必须包含以下请求头:

请求头	说明
`X-GatePay-Certificate-ClientId`	创建应用时分配给你的 `ClientId`，详情可参考接入总览。
`X-GatePay-Timestamp`	创建请求时的当前 UTC 毫秒时间戳。时间偏差超过 10 秒的请求会被拒绝。
`X-GatePay-Nonce`	用于防止重放攻击的随机字符串。建议长度不超过 32 个字符，且仅包含字母和数字。
`X-GatePay-Signature`	计算得到的请求签名（见下方签名生成步骤）。
`X-GatePay-On-Behalf-Of`	机构代理请求头。除创建子账户、查询子账户详情、分页查询子账户外，其余机构接口均需携带；普通商户接口不展示该请求头。

签名字符串格式

签名基于三行字符串计算，每行都以换行符结尾 (\n):

<request_timestamp>\n<request_nonce>\n<request_body>\n

其中：

<request_timestamp> 取值为 X-GatePay-Timestamp
<request_nonce> 取值为 X-GatePay-Nonce
<request_body> 为请求的原始 JSON 请求体；如果没有请求体，则为空字符串

签名生成步骤

按以下步骤计算 X-GatePay-Signature 请求头的值:

生成唯一的 X-GatePay-Timestamp （当前 UTC 毫秒时间）
生成随机 X-GatePay-Nonce (长度不超过 32 个字符，且仅包含字母和数字)
将原始 JSON 请求体读取为 request_body; 如果没有请求体则使用空字符串
构造签名字符串: timestamp\nnonce\nbody\n
使用你的 Payment API Secret 作为密钥计算 HMAC-SHA512
将结果编码为十六进制字符串
将计算得到的签名放入 X-GatePay-Signature 请求头

请求结构示例

以下示例仅用于说明签名字符串的组成方式，不表示某个具体业务接口的完整请求参数。实际字段应以对应 API Reference 页面和 OpenAPI 定义为准。

POST /v1/pay/checkout/order HTTP/1.1
Host: openplatform.gateapi.io
Content-Type: application/json
X-GatePay-Certificate-ClientId: your_client_id
X-GatePay-Timestamp: 1234567890000
X-GatePay-Nonce: abc123def456ghi789
X-GatePay-Signature: <computed_hmac_sha512_hex_signature>

{
  "merchantTradeNo": "order_12345",
  "orderAmount": "100.50",
  "currency": "USD"
}

支付结果回调

回调概述

GatePay 会通过 HTTP POST 请求向你配置的回调 URL 发送异步支付通知，用于告知你的系统支付状态变化。有关回调事件和处理方式的完整说明，请参见通知与回调指南。

回调载荷结构

以下示例用于帮助理解回调封装格式。不同业务线在 data 字段中的业务对象会有所不同，处理时应结合具体产品文档和对应回调 reference 一并理解。 GatePay 会 POST 以下结构的 JSON 载荷:

{
  "bizType": "TRANSFER_ADDRESS",
  "bizId": "329782527190433792",
  "bizStatus": "TRANSFERRED_ADDRESS_DELAY",
  "client_id": "iVNJZdekOCMJIsmV",
  "data": "{\"merchantTradeNo\":\"1894789022551797760\"}"
}

其中：

字段	类型	说明
`bizType`	字符串	业务事件类型（例如 `TRANSFER_ADDRESS`, `PAYMENT_ORDER`).
`bizId`	字符串	支付订单或业务交易的唯一标识.
`bizStatus`	字符串	交易当前状态（例如 `TRANSFERRED_ADDRESS_DELAY`, `SUCCESS`).
`client_id`	字符串	与支付订单关联的 `client_id`.
`data`	字符串	以 JSON 字符串表示的业务数据。具体结构取决于 `bizType`。

预期回调响应

你的回调接口必须返回一个 JSON 对象，表示处理成功:

字段	取值	说明
`returnCode`	`SUCCESS` \| `FAIL`	`SUCCESS` 表示回调处理成功；`FAIL` 表示处理失败。
`returnMessage`	字符串	用于说明结果的可读消息（成功时为空字符串）。

成功响应示例:

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

失败响应示例:

{
  "returnCode": "FAIL",
  "returnMessage": "Database connection failed"
}

回调验签步骤

你收到的每个回调都必须进行验签，以确认其来自 GatePay 且未被篡改:

提取 X-GatePay-Timestamp 请求头
提取 X-GatePay-Nonce 请求头
提取 X-GatePay-Signature 请求头
读取原始 JSON 回调请求体
按以下格式构造签名字符串: timestamp\nnonce\nbody\n
使用你的 Payment API Secret 作为密钥计算 HMAC-SHA512
将计算得到的签名与 X-GatePay-Signature 请求头值进行比对
仅当签名完全一致时才处理回调

重要: 如果签名不匹配，应拒绝该回调，因为它可能是伪造或已被篡改的。

回调请求头

GatePay 向你的接口发送回调时，会包含以下请求头:

请求头	说明
`X-GatePay-Timestamp`	GatePay 发送回调时的时间戳。
`X-GatePay-Nonce`	签名中包含的随机字符串。
`X-GatePay-Signature`	GatePay 计算得到的 HMAC-SHA512 签名。

时间窗口说明

文档中涉及两个不同的时间窗口，它们分别服务于不同场景：

场景	时间窗口	含义
商户发起 API 请求	10 秒	GatePay 对请求时间戳的验收窗口。超过该偏差的请求可能被拒绝。
商户接收并验证回调	5 分钟（建议值）	商户侧用于防重放的推荐校验窗口，不表示 GatePay 回调只在 5 分钟内有效。

接入时建议这样理解：

10 秒 约束的是你发往 GatePay 的请求。
5 分钟 是商户在接收回调时可采用的安全校验策略建议值。
如果你的系统希望采用更严格的回调时间窗口，可以在可接受的网络延迟范围内自行收紧。

工具与资源

签名验证工具

GatePay 提供在线工具，帮助你在开发阶段调试和验证签名: GatePay 签名验证工具该工具可用于:

使用示例数据测试签名生成
验证计算签名是否与预期值一致
调试签名相关接入问题

错误处理

有关完整错误码和 API 错误处理最佳实践，请参见错误码与最佳实践指南。

安全最佳实践

安全密钥存储: 在服务端安全存储 Payment API Secret 和 Authorization Secret。不要在客户端代码或版本控制中暴露这些密钥。
nonce 唯一性: 确保每个请求都使用唯一 nonce，以防止重放攻击。
时间戳校验: 对商户主动请求，确保时间戳偏差不超过 10 秒；对回调验签，可使用不超过 5 分钟的本地校验窗口作为防重放策略。
签名验证: 处理任何敏感操作前始终验证回调签名。
仅使用 HTTPS: 与 GatePay 的所有通信都必须使用 HTTPS 和 TLS 1.2 或以上版本。
回调幂等性： 将回调处理器设计为幂等，因为 GatePay 在未收到成功响应时可能会重试回调。
错误消息: 不要在返回给客户端的错误消息中暴露敏感信息（如密钥或内部系统详情）。

​API 标准与协议

​传输与数据格式

​签名与验签

​响应判定

​统一响应结构

​请求参数规范

​商户订单号 (merchantTradeNo)

​交易金额

​时间戳格式

​请求头与签名

​必填请求头

​签名字符串格式

​签名生成步骤

​请求结构示例

​支付结果回调

​回调概述

​回调载荷结构

​预期回调响应

​回调验签步骤

​回调请求头

​时间窗口说明

​工具与资源

​签名验证工具

​错误处理

​安全最佳实践

​相关文档