> ## 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 API 所需的认证机制、安全协议、请求签名以及回调验签要求。

## 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`         | 对象 / 数组 / 字符串 / null | API 返回的业务数据。 失败响应中为空。                  |

## 请求参数规范

### 商户订单号 (`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`，详情可参考 [接入总览](/essentials/version/100/cn/common/overview)。 |
| `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 定义为准。

```json theme={null}
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 发送异步支付通知，用于告知你的系统支付状态变化。

有关回调事件和处理方式的完整说明，请参见 [通知与回调](/essentials/version/100/cn/common/notification) 指南。

### 回调载荷结构

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

GatePay 会 POST 以下结构的 JSON 载荷:

```json theme={null}
{
  "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` | 字符串                 | 用于说明结果的可读消息（成功时为空字符串）。            |

**成功响应示例:**

```json theme={null}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
```

**失败响应示例:**

```json theme={null}
{
  "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-Timestamp` | GatePay 发送回调时的时间戳。            |
| `X-GatePay-Nonce`     | 签名中包含的随机字符串。                  |
| `X-GatePay-Signature` | GatePay 计算得到的 HMAC-SHA512 签名。 |

## 时间窗口说明

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

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

接入时建议这样理解：

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

## 工具与资源

### 签名验证工具

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

[GatePay 签名验证工具](https://www.gate.com/zh/gatepay/public/signUtil)

该工具可用于:

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

## 错误处理

有关完整错误码和 API 错误处理最佳实践，请参见 [错误码与最佳实践](/essentials/version/100/cn/common/error) 指南。

## 安全最佳实践

1. **安全密钥存储:** 在服务端安全存储 Payment API Secret 和 Authorization Secret。不要在客户端代码或版本控制中暴露这些密钥。

2. **nonce 唯一性:** 确保每个请求都使用唯一 nonce，以防止重放攻击。

3. **时间戳校验:** 对商户主动请求，确保时间戳偏差不超过 10 秒；对回调验签，可使用不超过 5 分钟的本地校验窗口作为防重放策略。

4. **签名验证:** 处理任何敏感操作前始终验证回调签名。

5. **仅使用 HTTPS:** 与 GatePay 的所有通信都必须使用 HTTPS 和 TLS 1.2 或以上版本。

6. **回调幂等性：** 将回调处理器设计为幂等，因为 GatePay 在未收到成功响应时可能会重试回调。

7. **错误消息:** 不要在返回给客户端的错误消息中暴露敏感信息（如密钥或内部系统详情）。

## 相关文档

* [接入总览](/essentials/version/100/cn/common/overview) - 应用配置与凭证设置
* [通知与回调](/essentials/version/100/cn/common/notification) - 详细回调事件处理
* [错误码与最佳实践](/essentials/version/100/cn/common/error) - 错误码参考与故障排查