商户接入指南
本指南介绍接入 GatePay API 所需的配置步骤，包括凭证获取和回调地址配置。服务地址
所有 GatePay API 均通过以下 Base URL 访问：接入步骤
1. 登录并完成商户注册
- 登录 GatePay 商户后台。
- 完成商户注册流程，填写所有必要的企业信息。
- 确保账户已激活并通过验证。
2. 创建应用
- 进入商户后台的应用配置页面。
- 点击创建新应用。
- 填写应用名称和描述。
- 同意服务条款后点击确认创建。
3. 获取 ClientId
- 进入应用列表页面。
- 找到刚创建的应用。
- 复制 ClientId，后续所有 API 请求都需要用到。
X-GatePay-Certificate-ClientId 请求头在每次请求中传入。
4. 生成 API 密钥
- 进入应用配置中的开发者设置。
- 生成以下凭证：
- Payment API Secret — 用于支付类 API 请求签名及回调验签。
- Authorization Secret — 用于授权类 API 请求签名（如适用）。
5. 配置回调地址
- 在应用设置中找到回调地址配置项。
- 填入你的服务器回调接收地址（例如：
https://yourserver.com/gateapi/callback）。 - 测试回调地址，确保可正常访问并返回正确响应。
- 保存配置。
- 必须为有效的 HTTPS 地址。
- 收到通知后必须返回 HTTP 200。
- 必须使用 Payment API Secret 对回调签名进行验签。
- 建议实现幂等处理，防止重复投递导致业务异常。
核心凭证说明
| 凭证 | 说明 | 用途 |
|---|---|---|
| ClientId | GatePay 分配的应用唯一标识 | 所有请求中通过 X-GatePay-Certificate-ClientId 传入 |
| Payment API Secret | 支付类 API 的服务端签名密钥 | 用于支付端点的 HMAC-SHA512 签名及回调验签 |
| Authorization Secret | 授权类 API 的服务端签名密钥（如适用） | 用于授权端点的 HMAC-SHA512 签名 |
| 回调地址 | 接收异步通知的服务端地址 | 接收支付状态变更、出款结果等异步事件通知 |
SDK
GatePay 提供官方 SDK 以简化集成：| SDK | 语言 | 最低版本 | 仓库地址 |
|---|---|---|---|
gatepay-sdk-go | Go | 1.21+ | https://github.com/gatepay2025/gatepay-sdk-go |
结果确认策略
对于所有异步操作，建议采用回调为主、查询兜底的模式：- 主动接收回调： 监听 GatePay 发送的回调通知，收到后立即处理。
- 查询兜底： 若在合理时间内（如 5～10 分钟）未收到回调，主动调用对应查询接口核实状态。
- 支付订单状态（使用查询订单详情）
- 退款状态
- 出款状态
- 子账户创建状态
上线前安全检查
- ClientId 和 API 密钥已通过环境变量或密钥管理系统安全存储
- 所有 API 请求使用 TLS 1.2 及以上的 HTTPS
- 请求签名已按 HMAC-SHA512 正确生成
- 回调签名在收到后立即验证
- 回调端点验签成功后返回 HTTP 200
- 回调处理已实现幂等逻辑
- 请求时间戳已校验（偏差 < 10 秒）
- Nonce 唯一，已做重放攻击检测
- 密钥未硬编码或提交至版本控制
- 错误响应已记录日志，且不包含敏感数据
相关文档
- 认证与安全 — 签名生成与回调验签详解
- API Reference 总览 — 所有可用接口列表
- 支付指南 — 支付集成流程
- 异步通知回调指南 — 回调处理与重试机制
- 错误码与最佳实践 — 常见问题排查