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

# 对账

> 本文档介绍 Gate Pay 的对账能力，适用于日终对账、财务系统同步、异常排查与审计追踪等场景。

## 概述

Gate Pay 对账能力支持商户通过 API 按时间范围批量拉取订单明细。后续将陆续增加其他类型的订单列表查询，以及资金流水查询能力。

常见使用场景包括：

* 日终将 Gate Pay 收单、下发数据与内部账本核对
* 对接 BI 或数据仓库，定时同步订单明细
* 结合订单号、状态筛选，排查单笔或批量异常
* 作为支付/出款回调的兜底数据源，确认最终状态

***

## 前置条件

在接入对账能力之前，需先完成以下准备工作：

1. **创建应用**：在商户后台创建 GatePay 应用
2. **获取 ClientId**：获取用于 API 认证的 ClientId
3. **配置签名密钥**：配置请求签名所需的密钥
4. **配置回调地址**：设置用于接收异步通知的回调接口地址

详细配置说明请参见 [接入总览](/essentials/version/100/cn/common/overview) 和 [认证与安全](/essentials/version/100/cn/common/authentication)。

***

## 对账接入步骤

### 第一步：拉取收款订单列表

按创建时间范围分页查询收款订单，支持按订单类型、状态、支付方式等条件筛选。

**请求接口：**

```http theme={null}
GET /payment/open/v1/pay/order/list
```

该接口可获取指定时间窗口内的收款订单明细，包括订单号、金额、状态、手续费及链上信息等。完整入参、出参见 API 参考。

### 第二步：拉取下发出订单列表

按创建时间范围分页查询下发订单，支持按渠道、订单状态、审批状态等条件筛选。

**请求接口：**

```http theme={null}
GET /withdraw/open/v1/withdraw/suborder/query
```

该接口可获取指定时间窗口内的下发子单明细，包括批次号、金额、状态、链上信息等。完整入参、出参见 API 参考。

### 第三步：与内部系统核对

将前两步拉取到的订单数据与商户内部账本、业务系统或财务记录按需核对，确认数据一致。具体核对维度与流程由商户根据自身业务自行定义。

### 第四步：兜底查询

列表查询可作为兜底机制，用于校验回调是否完整送达、排查差异或追溯历史数据。建议将回调处理与列表拉取作为互补手段，而非只依赖其中一种。

***

## 订单状态

### 收款订单状态

收款订单 `status` 常见取值如下：

| 状态   | API 枚举值       | 说明           |
| ---- | ------------- | ------------ |
| 待支付  | `WAIT_PAY`    | 订单已创建，尚未完成支付 |
| 支付中  | `PAYING`      | 支付处理中        |
| 支付成功 | `PAY_SUCCESS` | 支付完成，可纳入入账对账 |
| 支付失败 | `PAY_FAIL`    | 支付未成功        |
| 已过期  | `EXPIRED`     | 超过有效支付时间     |
| 已取消  | `CANCELLED`   | 订单已取消        |

### 下发订单状态

下发订单 `status` 常见取值如下：

| 状态   | API 枚举值          | 说明           |
| ---- | ---------------- | ------------ |
| 已创建  | `CREATED`        | 订单已创建        |
| 待处理  | `PENDING`        | 等待处理         |
| 审核中  | `UNDER_REVIEW`   | 审批流程中        |
| 处理中  | `PROCESSING`     | 资金处理中        |
| 下发成功 | `PAYOUT_SUCCESS` | 出款完成，可纳入出账对账 |
| 下发失败 | `PAYOUT_FAIL`    | 出款未成功或已回退    |

***

## 错误处理

查询列表时，可能遇到以下典型问题：

| 场景      | 说明                                    | 建议处理方式                                                 |
| ------- | ------------------------------------- | ------------------------------------------------------ |
| 时间范围非法  | `endTime` / `end_time` 早于对应起始时间，或跨度超限 | 按日或按小时切分窗口；遵守 API 参考中的跨度上限                             |
| 分页参数异常  | `count` 缺失或超过上限                       | 设置合理 `count`，大区间用 `page` 逐页拉取                          |
| 状态筛选不匹配 | 传入的 `status` 不属于当前订单类型枚举              | 对照本文「订单状态」与 API 参考枚举表                                  |
| 鉴权失败    | 签名错误或 Key 无查询权限                       | 检查 Payment API Secret、`X-GatePay-Signature` 及 Key 权限范围 |
| 数据量过大   | 单次响应超时或触发限流                           | 缩小时间窗口、降低并发，必要时错峰调度                                    |

建议：对网络超时等临时性错误采用指数退避重试；对参数非法、权限不足等永久性错误，应先修复后再发起请求。

***

## 对账与审计

### 日终对账流程

建议定期将 Gate Pay 订单数据与内部系统记录进行核对：

1. **划定对账窗口**：按业务日设置 `startTime` / `endTime`（收款）或 `start_time` / `end_time`（下发）
2. **分页拉取列表**：分别调用收款、下发列表接口直至无下一页
3. **核对金额字段**：确认金额、手续费、结算/到账金额与内部预期一致
4. **核对终态**：终态订单数量与回调处理记录一致
5. **留存差异单**：无法自动匹配的订单进入人工复核队列

### 差异排查

若某笔订单与内部记录不一致，建议按以下步骤排查：

1. **确认关联键**：核对 `merchantTradeNo` 与 `orderId`（收款），或 `merchantWithdrawId` 与 `suborderId`（下发）是否对应同一笔业务
2. **查看订单状态**：确认是否处于中间态（如 `PAYING`、`PROCESSING`）
3. **核对退款与部分成功**：检查 `refund_amount` 或下发失败原因
4. **链上佐证**：Web3 场景可通过 `hashes` / `txId` 在区块浏览器二次确认
5. **兜底单笔查询**：必要时调用单笔详情接口或 [商户 MCP](/essentials/version/100/cn/common/gatePayMerchantMCP) 工具补充字段

***

## 请求签名与校验

所有对账请求都必须使用 Gate Pay 统一签名机制完成签名：

* 使用 Payment API Secret 对请求体按 `timestamp\nnonce\nbody\n` 规则计算 HMAC-SHA512
* 将签名结果放入请求头 `X-GatePay-Signature`

关于请求签名、签名生成方式，请参见 [认证与安全](/essentials/version/100/cn/common/authentication) 相关文档。

***

## 最佳实践

* **按窗口切分拉取**：大时间范围按日或按小时分批请求，避免单次数据量过大
* **双通道核对**：回调驱动实时状态，列表接口做日终兜底
* **统一对账主键**：在内部系统中固定 `merchantTradeNo` / `merchantWithdrawId` 的映射规则
* **留存原始响应**：对账任务保留 API 原始 JSON，便于审计与重跑
* **监控中间态堆积**：对长时间处于 `PAYING`、`PROCESSING` 的订单设置告警
* **链上交叉验证**：关键 Web3 交易通过 `hashes` / `txId` 二次确认
* **每日对账**：在 T+1 日终完成前一日全量核对
* **保护签名密钥**：Payment API Secret 不得出现在日志或暴露给未授权人员
* **关注限流**：大批量拉取时控制并发与请求频率
* **差异闭环**：为无法自动匹配的记录建立人工复核与补单流程

***

## 相关文档

* [接入总览](/essentials/version/100/cn/common/overview)
* [认证与安全](/essentials/version/100/cn/common/authentication)
* [通知与回调](/essentials/version/100/cn/common/notification)
* [余额](/essentials/version/100/cn/common/balance)
* [出金](/essentials/version/100/cn/outflow/payout)
* [错误码与最佳实践](/essentials/version/100/cn/common/error)