快速开始 - Gate Pay DOCS

概述

本页提供一个面向正式接入环境的最小可运行示例，帮助商户从 0 到 1 跑通第一条 GatePay 支付链路。本文档以正式接入流程为主。在开始联调前，建议先完成商户资质、应用创建、密钥配置与回调地址准备。如果你是第一次接入，建议按以下顺序完成：

获取 ClientId 与签名密钥
按签名规则生成请求头
创建第一笔收银台订单
接收并验证异步回调
使用查单接口做最终确认

第一步：准备凭证

在商户后台完成应用创建后，至少准备以下信息：

凭证	用途
`ClientId`	作为 `X-GatePay-Certificate-ClientId` 请求头传入
Payment API Secret	用于生成支付类接口签名
回调地址	用于接收异步通知

如果你尚未完成这一步，请先参见总览与认证。

第二步：构造签名请求头

GatePay 请求签名至少需要以下头信息：

X-GatePay-Certificate-ClientId
X-GatePay-Timestamp
X-GatePay-Nonce
X-GatePay-Signature

签名串的核心结构为：

timestamp\nnonce\nbody\n

接入建议：

timestamp 使用 UTC 毫秒时间戳
nonce 使用一次性随机串
body 必须与实际发送报文完全一致
先本地打印签名串，再计算签名，最容易定位联调问题

Python 签名示例

import hmac
import hashlib

timestamp = "1710000000000"
nonce = "abc123xyz789"
body = '{"merchantTradeNo":"M202604150001","currency":"USDT","orderAmount":"10.00"}'
secret = "your_payment_api_secret"

payload = f"{timestamp}\n{nonce}\n{body}\n"
signature = hmac.new(
    secret.encode("utf-8"),
    payload.encode("utf-8"),
    hashlib.sha512,
).hexdigest()

print(signature)

Node.js 签名示例

const crypto = require("crypto");

const timestamp = "1710000000000";
const nonce = "abc123xyz789";
const body = '{"merchantTradeNo":"M202604150001","currency":"USDT","orderAmount":"10.00"}';
const secret = "your_payment_api_secret";

const payload = `${timestamp}\n${nonce}\n${body}\n`;
const signature = crypto
  .createHmac("sha512", secret)
  .update(payload, "utf8")
  .digest("hex");

console.log(signature);

完整签名规则请参见安全与签名。

第三步：创建第一笔支付订单

下面示例使用托管收银台支付作为第一条链路，因为它最适合快速验证签名、下单、回调和查单。 请求接口

POST /v1/pay/checkout/order

最小请求示例 说明：

当前公开文档中的普通商户 API 示例默认不展示 X-GatePay-On-Behalf-Of 请求头。
实际对接时，该字段的具体取值应按你的主体归属方案与接口定义填写。

curl -X POST "https://openplatform.gateapi.io/v1/pay/checkout/order" \
  -H "Content-Type: application/json" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1710000000000" \
  -H "X-GatePay-Nonce: abc123xyz789" \
  -H "X-GatePay-Signature: generated_signature" \
  -d '{
    "merchantTradeNo": "M202604150001",
    "currency": "USDT",
    "orderAmount": "10.00",
    "goods": {
      "goodsName": "Demo Order",
      "goodsDetail": "First payment integration test"
    },
    "callbackUrl": "https://merchant.example.com/webhook/gatepay",
    "returnUrl": "https://merchant.example.com/result"
  }'

普通商户请求仅需携带 GatePay 标准签名请求头。 响应中重点关注

字段	说明
`prepayId`	GatePay 预订单号，后续查单会用到
`location`	托管收银台跳转地址
`qrContent`	某些模式下返回的二维码内容链接

创建成功后，商户前端应直接使用返回的 location 跳转，不要手动拼接页面地址。

第四步：接收异步回调

用户完成支付后，GatePay 会向你配置的回调地址发送异步通知。 回调示例

{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "your_client_id",
  "data": "{\"merchantTradeNo\":\"M202604150001\",\"orderAmount\":\"10.00\"}"
}

你的回调处理逻辑至少应做到：

验签
按业务唯一标识做幂等
更新本地订单状态
返回 HTTP 200 与约定成功响应

统一回调说明请参见通知。

第五步：查单做最终确认

对于支付链路，推荐采用“回调优先，查单兜底”的方式。 请求接口

GET /v2/pay/order/query

最小查询示例

curl -X GET "https://openplatform.gateapi.io/v2/pay/order/query?merchantTradeNo=M202604150001" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1710000005000" \
  -H "X-GatePay-Nonce: query123" \
  -H "X-GatePay-Signature: generated_signature" \

对支付确认链路，建议把以下两个信号分开处理：

回调用于实时推进业务流程
查单用于最终确认和对账

首次上线前检查清单

已确认 ClientId、Secret 与回调地址配置无误
已在服务端实现签名与验签
已保存 merchantTradeNo 与 prepayId
已实现回调幂等
已接入查单接口作为兜底
已准备生产监控与失败告警

下一步建议

如果你要接入完整收款能力，继续阅读支付
如果你要接入法币结算，继续阅读 OTC
如果你要接入批量出金，继续阅读出金

​概述

​第一步：准备凭证

​第二步：构造签名请求头

​Python 签名示例

​Node.js 签名示例

​第三步：创建第一笔支付订单

​第四步：接收异步回调

​第五步：查单做最终确认

​首次上线前检查清单

​下一步建议

概述