> ## 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.

# 快速开始

> 用最短路径跑通 GatePay 的第一条支付链路，包括签名、下单、回调与查单。

## 概述

本页提供一个面向正式接入环境的最小可运行示例，帮助商户从 0 到 1 跑通第一条 GatePay 支付链路。

本文档以正式接入流程为主。在开始联调前，建议先完成商户资质、应用创建、密钥配置与回调地址准备。

如果你是第一次接入，建议按以下顺序完成：

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

## 第一步：准备凭证

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

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

如果你尚未完成这一步，请先参见 [总览](/essentials/version/100/cn/common/overview) 与 [认证](/essentials/version/100/cn/common/authentication)。

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

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

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

签名串的核心结构为：

```text theme={null}
timestamp\nnonce\nbody\n
```

接入建议：

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

### Python 签名示例

```python theme={null}
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 签名示例

```javascript theme={null}
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);
```

完整签名规则请参见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。

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

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

**请求接口**

```http theme={null}
POST /v1/pay/checkout/order
```

**最小请求示例**

说明：

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

```bash theme={null}
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 会向你配置的回调地址发送异步通知。

**回调示例**

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "your_client_id",
  "data": "{\"merchantTradeNo\":\"M202604150001\",\"orderAmount\":\"10.00\"}"
}
```

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

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

统一回调说明请参见 [通知](/essentials/version/100/cn/common/notification)。

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

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

**请求接口**

```http theme={null}
GET /v2/pay/order/query
```

**最小查询示例**

```bash theme={null}
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`
* 已实现回调幂等
* 已接入查单接口作为兜底
* 已准备生产监控与失败告警

## 下一步建议

* 如果你要接入完整收款能力，继续阅读 [支付](/essentials/version/100/cn/inflow/payment/payment)
* 如果你要接入法币结算，继续阅读 [OTC](/essentials/version/100/cn/otc)
* 如果你要接入批量出金，继续阅读 [出金](/essentials/version/100/cn/outflow/payout)