> ## 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 所需的应用创建、凭证获取、回调配置与上线前检查项。

# 商户接入

本指南介绍接入 GatePay API 所需的配置步骤，包括凭证获取和回调地址配置。

如果你希望先快速跑通第一条链路，再回头补充完整配置，建议先阅读 [Quickstart](/essentials/version/100/cn/common/quickstart)。本页更适合作为正式上线前的接入准备清单与配置说明。

## 服务地址

所有 GatePay API 均通过以下 Base URL 访问：

```
https://openplatform.gateapi.io
```

## 接入步骤

### 1. 登录并完成商户注册

* 登录 **GatePay 商户后台**。
* 完成商户注册流程，填写所有必要的企业信息。
* 确保账户已激活并通过验证。

### 2. 创建应用

* 进入商户后台的**应用配置**页面。
* 点击**创建新应用**。
* 填写应用名称和描述。
* 同意服务条款后点击**确认创建**。

### 3. 获取 ClientId

* 进入**应用列表**页面。
* 找到刚创建的应用。
* 复制 **ClientId**，后续所有 API 请求都需要用到。

**说明：** ClientId 通过 `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-java`                 | Java                 | 17+     | [https://github.com/gate/gatepay-sdk-java](https://github.com/gate/gatepay-sdk-java)                                 |
| `gatepay-sdk-go`                   | Go                   | 1.6+    | [https://github.com/gate/gatepay-sdk-go](https://github.com/gate/gatepay-sdk-go)                                     |
| `gatepay-sdk-python`               | Python               | 以仓库说明为准 | [https://github.com/gate/gatepay-sdk-python](https://github.com/gate/gatepay-sdk-python)                             |
| `gatepay-sdk-android`              | Android              | 以仓库说明为准 | [https://github.com/gate/gatepay-sdk-android](https://github.com/gate/gatepay-sdk-android)                           |
| `gatepay-sdk-ios`                  | iOS                  | 以仓库说明为准 | [https://github.com/gate/gatepay-sdk-ios](https://github.com/gate/gatepay-sdk-ios)                                   |
| `gatepay-call-payment-sdk-android` | Android Call Payment | 以仓库说明为准 | [https://github.com/gate/gatepay-call-payment-sdk-android](https://github.com/gate/gatepay-call-payment-sdk-android) |
| `gatepay-call-payment-sdk-iOS`     | iOS Call Payment     | 以仓库说明为准 | [https://github.com/gate/gatepay-call-payment-sdk-iOS](https://github.com/gate/gatepay-call-payment-sdk-iOS)         |

最新官方 SDK 与客户端仓库请统一以 [https://github.com/gate](https://github.com/gate) 为准。使用官方 SDK 可简化签名生成、请求构造和回调验签流程。具体用法请参考对应仓库文档。

## 结果确认策略

对于所有异步操作，建议采用**回调为主、查询兜底**的模式：

1. **主动接收回调：** 监听 GatePay 发送的回调通知，收到后立即处理。
2. **查询兜底：** 若在合理时间内（如 5～10 分钟）未收到回调，主动调用对应查询接口核实状态。

该模式可确保即使回调延迟或丢失，业务结果也能得到可靠确认。

**适用场景：**

* 支付订单状态（使用 [查询订单详情](/api-reference/version/100/cn/endpoint/checkout/orderQuery)）
* 退款状态
* 出款状态
* 机构模式下的子账户创建状态（如适用）

## 上线前安全检查

* [ ] ClientId 和 API 密钥已通过环境变量或密钥管理系统安全存储
* [ ] 所有 API 请求使用 TLS 1.2 及以上的 HTTPS
* [ ] 请求签名已按 HMAC-SHA512 正确生成
* [ ] 回调签名在收到后立即验证
* [ ] 回调端点验签成功后返回 HTTP 200
* [ ] 回调处理已实现幂等逻辑
* [ ] 请求时间戳已校验（偏差 \< 10 秒）
* [ ] Nonce 唯一，已做重放攻击检测
* [ ] 密钥未硬编码或提交至版本控制
* [ ] 错误响应已记录日志，且不包含敏感数据

## 相关文档

* [认证与安全](/essentials/version/100/cn/common/authentication) — 签名生成与回调验签详解
* [API Reference](/api-reference/version/100/cn/introduction) — 所有可用接口与分组入口
* [支付](/essentials/version/100/cn/inflow/payment/payment) — 支付集成流程
* [通知](/essentials/version/100/cn/common/notification) — 回调处理与重试机制
* [错误码与最佳实践](/essentials/version/100/cn/common/error) — 常见问题排查

## 阅读建议

如果你是第一次接入 GatePay，建议按以下顺序阅读：

1. 先阅读本页，完成应用、密钥与回调地址的准备。
2. 再阅读 [认证与安全](/essentials/version/100/cn/common/authentication)，确认签名与验签方式。
3. 如果接入支付能力，继续阅读 [支付](/essentials/version/100/cn/inflow/payment/payment)。
4. 如果接入 OTC 或出金能力，再阅读对应产品文档和 API Reference。