跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​
API 标准与协议

​
传输与数据格式

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

​
签名与验签

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

​
响应判定

请始终按以下方式判断 API 响应结果：
  1. 先检查 HTTP 状态码
  2. 再检查响应体中的 status、code、label 和 errorMessage 字段
  3. 如果请求成功，则从 data 字段提取业务数据

​
统一响应结构

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

​
请求参数规范

​
商户订单号 (merchantTradeNo)

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

​
交易金额

属性规格
数据类型字符串（以字符串形式表示数值）
小数精度最多 6 位小数
单笔最小金额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 请求头的值:
  1. 生成唯一的 X-GatePay-Timestamp （当前 UTC 毫秒时间）
  2. 生成随机 X-GatePay-Nonce (长度不超过 32 个字符，且仅包含字母和数字)
  3. 将原始 JSON 请求体读取为 request_body; 如果没有请求体则使用空字符串
  4. 构造签名字符串: timestamp\nnonce\nbody\n
  5. 使用你的 Payment API Secret 作为密钥计算 HMAC-SHA512
  6. 将结果编码为十六进制字符串
  7. 将计算得到的签名放入 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 对象，表示处理成功:
字段取值说明
returnCodeSUCCESS | FAILSUCCESS 表示回调处理成功；FAIL 表示处理失败。
returnMessage字符串用于说明结果的可读消息（成功时为空字符串）。
成功响应示例: 
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
失败响应示例: 
{
  "returnCode": "FAIL",
  "returnMessage": "Database connection failed"
}

​
回调验签步骤

你收到的每个回调都必须进行验签，以确认其来自 GatePay 且未被篡改:
  1. 提取 X-GatePay-Timestamp 请求头
  2. 提取 X-GatePay-Nonce 请求头
  3. 提取 X-GatePay-Signature 请求头
  4. 读取原始 JSON 回调请求体
  5. 按以下格式构造签名字符串: timestamp\nnonce\nbody\n
  6. 使用你的 Payment API Secret 作为密钥计算 HMAC-SHA512
  7. 将计算得到的签名与 X-GatePay-Signature 请求头值进行比对
  8. 仅当签名完全一致时才处理回调
重要: 如果签名不匹配，应拒绝该回调，因为它可能是伪造或已被篡改的。

​
回调请求头

GatePay 向你的接口发送回调时，会包含以下请求头:
请求头说明
X-GatePay-TimestampGatePay 发送回调时的时间戳。
X-GatePay-Nonce签名中包含的随机字符串。
X-GatePay-SignatureGatePay 计算得到的 HMAC-SHA512 签名。

​
时间窗口说明

文档中涉及两个不同的时间窗口，它们分别服务于不同场景：
场景时间窗口含义
商户发起 API 请求10 秒GatePay 对请求时间戳的验收窗口。超过该偏差的请求可能被拒绝。
商户接收并验证回调5 分钟（建议值）商户侧用于防重放的推荐校验窗口，不表示 GatePay 回调只在 5 分钟内有效。
接入时建议这样理解：
  • 10 秒 约束的是你发往 GatePay 的请求。
  • 5 分钟 是商户在接收回调时可采用的安全校验策略建议值。
  • 如果你的系统希望采用更严格的回调时间窗口，可以在可接受的网络延迟范围内自行收紧。

​
工具与资源

​
签名验证工具

GatePay 提供在线工具，帮助你在开发阶段调试和验证签名: GatePay 签名验证工具 该工具可用于:
  • 使用示例数据测试签名生成
  • 验证计算签名是否与预期值一致
  • 调试签名相关接入问题

​
错误处理

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

​
安全最佳实践

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

​
相关文档