> ## 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 提供多种收款方式，以适配不同的商户和用户场景：

* **托管收银台支付**：由 GatePay 托管支付界面，支持二维码支付和链上动态地址支付
* **地址支付**：直接向动态生成或静态收款地址发起付款
* **支付拉起**：适用于移动端和客户端的应用内支付拉起场景

***

## 托管收银台支付

### 产品概述

托管收银台支付是由 GatePay 提供的完整收款能力。商户无需自行建设支付页面，GatePay 会统一处理以下方式：

* 二维码支付
* 链上动态地址支付（Web3）

### 支付流程

托管收银台支付流程主要包含三个步骤:

1. **创建预订单**: 商户创建预订单，并从 API 获取重定向信息。
2. **用户重定向**: 商户使用返回的 `location` URL 将用户重定向到 GatePay 托管收银台页面。
3. **异步通知**: 用户完成支付后，GatePay 会通过回调异步通知商户后端订单状态。

**重要**: 商户不得手动拼接收银台 URL。请始终使用 API 返回的 `location` 值.

### 查询支持的链

**请求**:

```
GET /v1/pay/address/chains
```

查询 Web3 地址支付支持的区块链网络列表。该接口可帮助你确认支付币种可使用哪些链.

### 创建托管收银台订单

**请求**:

```
POST /v1/pay/checkout/order
```

创建新的托管收银台订单。成功后，API 会返回 `location` 字段，你必须使用该字段将用户重定向到支付页面。该 URL 是进入 GatePay 托管收银台的唯一有效入口.

#### 参数说明

托管收银台订单的完整字段以 API Reference 和 OpenAPI 定义为准。不同收款模式下，请求体中可能会组合出现订单信息、用户信息、环境信息、商品信息以及链路相关字段。

接入时建议重点关注以下几类信息：

* 订单唯一标识，例如 `merchantTradeNo`
* 金额与币种信息
* 用户或终端上下文信息
* 商品与展示信息
* 回调与跳转地址
* 链路相关字段，例如链和币种组合

如果你是第一次接入，不建议只凭本页文字手写请求体；更稳妥的方式是直接对照对应的 API Reference 页面和 OpenAPI schema 实现。

#### 响应字段

| 字段          | 类型  | 说明                          |
| ----------- | --- | --------------------------- |
| `prepayId`  | 字符串 | 用于跟踪和查询的 GatePay 预订单 ID     |
| `location`  | 字符串 | 托管收银台重定向 URL。请将用户重定向到该 URL。 |
| `qrContent` | 字符串 | 二维码支付使用的二维码内容 (如适用)         |

#### 最小可运行示例

如果你想先跑通第一条支付链路，下面这组最小示例比字段总表更适合直接落地。

**创建订单**

```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: checkout001" \
  -H "X-GatePay-Signature: generated_signature" \
  -d '{
    "merchantTradeNo": "M202604150001",
    "currency": "USDT",
    "orderAmount": "10.00",
    "goods": {
      "goodsName": "Demo Order",
      "goodsDetail": "Checkout quickstart"
    },
    "callbackUrl": "https://merchant.example.com/webhook/gatepay",
    "returnUrl": "https://merchant.example.com/result"
  }'
```

**典型成功响应重点**

* 取得 `prepayId`
* 取得 `location`
* 前端使用 `location` 跳转

**后续链路**

1. 等待 `PAY` 回调
2. 再调用 `GET /v2/pay/order/query` 做最终确认
3. 关键订单建议同时保存 `merchantTradeNo` 与 `prepayId`

### 查询订单结果

**请求**:

```
GET /v2/pay/order/query
```

查询订单当前状态和详情。该接口是支付确认和对账的关键接口.

建议把该接口视为“支付结果最终确认接口”，而不是仅用于异常时排查。即使已经接收到成功回调，商户在关键流程中仍可按需结合本接口进行二次确认。

#### 不同支付方式的查询入口

* 托管收银台支付：`GET /v2/pay/order/query`
* 地址支付：`GET /v1/pay/address/query`
* 扫码 / Web 拉起支付：请按对应 API Reference 页面使用该产品实际暴露的查询接口

不要把不同产品线的查单接口混用。即使字段名称相近，不同产品的状态语义、金额字段和补充信息也可能不同。

#### 支付金额处理方式

支付金额的解释方式会根据订单类型而不同:

* **Gate 支付**（非地址）: 最终实付金额由以下字段表示 `orderAmount`.
* **地址支付**: 需要同时考虑 `waitAmountOnChain` 和 `doneAmountOnChain`:
  * `waitAmountOnChain`: 已检测到但尚未最终确认的链上金额
  * `doneAmountOnChain`: 已确认并入账到商户账户的链上金额

### 签名请求与回调

有关请求签名和回调验签的安全详情，请参见 [认证与安全](/essentials/version/100/cn/common/authentication)。

***

## 地址支付

地址支付支持直接向区块链地址收款。系统会根据订单参数动态生成支付地址，或使用预先配置的静态地址。

### 典型接入流程

1. **查询链**: 查询订单币种支持的链。
2. **创建订单**: 系统会生成并返回唯一收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写）
3. **用户支付**: 用户向收款地址转账。
4. **支付检测**: GatePay 检测链上交易，并通过回调通知你的后端。
5. **结果确认**: 通过回调确认支付，或使用查询 API 作为兜底。

### 订单状态

常见 `PAY_ADDRESS` 订单状态：

| 状态                       | 说明                               |
| ------------------------ | -------------------------------- |
| `PAY_SUCCESS`            | 支付成功且资金已入账                       |
| `PAY_ERROR`              | 支付失败；资金未入账                       |
| `PAY_CLOSE`              | 订单被商户或系统关闭                       |
| `PAY_EXPIRED_IN_PROCESS` | 订单有效期已过，但仍有部分链上交易未确认。确认后资金仍可能入账。 |

### 支付模式选择: 非兑换 vs. 兑换

**非兑换模式**: 资金按原支付币种入账。

**兑换模式**: 资金会在入账前兑换为其他币种。对于兑换模式订单，你可能需要查询支持的兑换币种。

#### 查询支持的兑换币种 (仅兑换模式)

**请求**:

```
GET /v1/pay/address/supportedconvertcurrencies
```

列出地址支付支持自动兑换的币种。

#### 创建地址支付订单

**请求**:

```
POST /v1/pay/address/create
```

系统会生成并返回唯一收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写）

当你在“非兑换”和“兑换”模式之间切换时，建议同时检查订单币种、支付币种和后续回调字段的解释方式，避免把不同模式下的字段含义混为一谈。

#### 查询地址支付订单

**请求**:

```
GET /v1/pay/address/query
```

查询地址支付订单当前状态，包括链上检测结果和确认状态。

***

## 静态地址支付

静态地址支付支持商户为长期或周期性收款场景配置固定收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写），适用于:

* 订阅或周期性账单
* 打赏或募资页面
* 商户结算账户
* 佣金分发

### 工作方式

1. **配置静态地址**: 使用保存接口为指定渠道和区块链配置固定收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写）
2. **复用地址**: 在多笔订单中复用同一地址和 Memo（如有），无需每次创建新地址
3. **自动检测**: GatePay 检测到静态地址收款后会发送通知。

如果同一 `channelId` 和 `chain` 已存在配置，API 会更新该配置.

#### 保存或更新静态地址配置

**请求**:

```
POST /v1/pay/fixedaddress/save
```

为指定的 `channelId` 和区块链网络（`chain`）保存或更新静态地址配置.

***

## 支付拉起

支付拉起支持移动应用或客户端 Web 应用中的应用内支付体验。该流程允许用户无需离开应用即可直接发起支付.

### 接入步骤

1. **服务端预订单**: 在后端使用收银台订单接口创建预订单。
2. **客户端拉起**: 将 `prepayId` 传给客户端应用。
3. **客户端查询**: 客户端可按需查询订单状态以更新界面。
4. **参数校验**: 拉起支付流程前校验支付参数。
5. **最终确认**: 用户返回后，通过服务端查询确认支付状态。

#### 客户端 SDK 参数校验

**请求**:

```
POST /v1/pay/open/sdk
```

校验支付参数并为支付拉起准备 SDK。发起客户端支付流程前，请使用该接口校验 `prepayId` 和其他参数.

#### 服务端预订单响应字段

创建用于支付拉起的预订单后，响应会包含:

| 字段          | 类型  | 说明                      |
| ----------- | --- | ----------------------- |
| `prepayId`  | 字符串 | 需要传给客户端 SDK 的预订单 ID     |
| `location`  | 字符串 | 重定向 URL（用于基于 Web 的支付拉起） |
| `qrContent` | 字符串 | 二维码内容（可选，用于二维码流程）       |

#### 客户端返回与支付确认

**关键提示**: 客户端应用返回商户页面后，重定向结果或客户端状态绝不能作为最终支付结果.

请始终通过服务端查询 `GET /v2/pay/order/query` 来确认支付状态。这可以确保:

* 系统中的支付状态准确
* 正确处理待确认或延迟支付
* 欺诈检测和对账

***

## 支付有效期与过期

### 默认有效期

默认情况下，订单自创建起 **1 小时** 内有效。可通过 `orderExpireTime` 参数配置有效期.

### 延迟支付处理

如果区块链交易在订单过期后提交，该支付会被归类为延迟支付。GatePay 支持两种处理模式:

* **非兑换延迟支付**: 即使订单已过期，资金在链上确认后仍会入账到商户账户.
* **兑换延迟支付**: 用户资金不会进入商户支付账户，该订单按失败处理.

***

## 退款

为保持向后兼容，GatePay 提供两个退款 API:

### 标准退款（推荐）

**请求**:

```
POST /v2/pay/order/refund
```

面向新接入的标准退款接口。所有新实现都应使用该接口.

### 兼容退款（旧版）

**请求**:

```
POST /v1/pay/order/refund
```

旧版退款接口。仅为已有接入保留，新接入必须使用 v2 接口.

需要特别区分：

* API 发起的退款：按本文档中的接口与回调模型接入
* 商户后台手工退款：处理进度以后台展示为准，不应假设一定沿用同样的 API 回调节奏

***

## 回调与异步通知

所有支付方式都支持异步回调，用于通知你的后端订单状态变化。有关完整的回调详情、载荷结构、签名与验签，请参见 [通知与回调](/essentials/version/100/cn/common/notification)。

GatePay 保证:

* 回调会按照具体订单流程中的回调配置或回调参数进行投递
* 回调 包含已签名载荷以便安全验证
* 如果首次投递失败，会进行多次回调重试

对于支付链路，建议始终把“回调通知”和“订单查询”组合使用：

* 回调用于及时推进业务流程
* 查询用于最终确认和兜底核验

如果你更希望先从完整链路开始接入，而不是按章节阅读，请先参见 [快速开始](/essentials/version/100/cn/common/quickstart)。

***

## 最佳实践

1. **始终验证回调**: 使用每次回调携带的签名进行验证。 见 [认证与安全](/essentials/version/100/cn/common/authentication).
2. **使用查询作为兜底**: 如果回调投递延迟或遗漏，请使用查询接口进行对账。
3. **处理延迟支付**: 实现逻辑以处理订单过期后到账的支付。
4. **监控金额字段**: 对于地址支付，请始终同时检查 `waitAmountOnChain` 和 `doneAmountOnChain`，以获得完整支付情况。
5. **保存 prepayId**: 保存订单创建时返回的 `prepayId`，用于跟踪和支持。
6. **实现幂等性**: 使用唯一的 `merchantTradeNo` 防止重复订单。

***

## 相关文档

* [通知与回调](/essentials/version/100/cn/common/notification)
* [认证与安全](/essentials/version/100/cn/common/authentication)
* [总览与配置](/essentials/version/100/cn/common/overview)
* [快速开始](/essentials/version/100/cn/common/quickstart)