概述
Gate Pay 对账能力支持商户通过 API 按时间范围批量拉取订单明细。后续将陆续增加其他类型的订单列表查询，以及资金流水查询能力。 常见使用场景包括：- 日终将 Gate Pay 收单、下发数据与内部账本核对
- 对接 BI 或数据仓库，定时同步订单明细
- 结合订单号、状态筛选，排查单笔或批量异常
- 作为支付/出款回调的兜底数据源，确认最终状态
前置条件
在接入对账能力之前，需先完成以下准备工作：- 创建应用：在商户后台创建 GatePay 应用
- 获取 ClientId：获取用于 API 认证的 ClientId
- 配置签名密钥：配置请求签名所需的密钥
- 配置回调地址：设置用于接收异步通知的回调接口地址
对账接入步骤
第一步：拉取收款订单列表
按创建时间范围分页查询收款订单，支持按订单类型、状态、支付方式等条件筛选。 请求接口：第二步：拉取下发出订单列表
按创建时间范围分页查询下发订单，支持按渠道、订单状态、审批状态等条件筛选。 请求接口：第三步：与内部系统核对
将前两步拉取到的订单数据与商户内部账本、业务系统或财务记录按需核对，确认数据一致。具体核对维度与流程由商户根据自身业务自行定义。第四步：兜底查询
列表查询可作为兜底机制，用于校验回调是否完整送达、排查差异或追溯历史数据。建议将回调处理与列表拉取作为互补手段，而非只依赖其中一种。订单状态
收款订单状态
收款订单status 常见取值如下：
下发订单状态
下发订单status 常见取值如下：
错误处理
查询列表时，可能遇到以下典型问题：
建议：对网络超时等临时性错误采用指数退避重试；对参数非法、权限不足等永久性错误，应先修复后再发起请求。
对账与审计
日终对账流程
建议定期将 Gate Pay 订单数据与内部系统记录进行核对：- 划定对账窗口：按业务日设置
startTime/endTime（收款）或start_time/end_time（下发） - 分页拉取列表：分别调用收款、下发列表接口直至无下一页
- 核对金额字段：确认金额、手续费、结算/到账金额与内部预期一致
- 核对终态：终态订单数量与回调处理记录一致
- 留存差异单：无法自动匹配的订单进入人工复核队列
差异排查
若某笔订单与内部记录不一致，建议按以下步骤排查：- 确认关联键：核对
merchantTradeNo与orderId（收款），或merchantWithdrawId与suborderId（下发）是否对应同一笔业务 - 查看订单状态：确认是否处于中间态（如
PAYING、PROCESSING） - 核对退款与部分成功：检查
refund_amount或下发失败原因 - 链上佐证：Web3 场景可通过
hashes/txId在区块浏览器二次确认 - 兜底单笔查询：必要时调用单笔详情接口或 商户 MCP 工具补充字段
请求签名与校验
所有对账请求都必须使用 Gate Pay 统一签名机制完成签名：- 使用 Payment API Secret 对请求体按
timestamp\nnonce\nbody\n规则计算 HMAC-SHA512 - 将签名结果放入请求头
X-GatePay-Signature
最佳实践
- 按窗口切分拉取：大时间范围按日或按小时分批请求，避免单次数据量过大
- 双通道核对：回调驱动实时状态，列表接口做日终兜底
- 统一对账主键：在内部系统中固定
merchantTradeNo/merchantWithdrawId的映射规则 - 留存原始响应：对账任务保留 API 原始 JSON，便于审计与重跑
- 监控中间态堆积：对长时间处于
PAYING、PROCESSING的订单设置告警 - 链上交叉验证：关键 Web3 交易通过
hashes/txId二次确认 - 每日对账：在 T+1 日终完成前一日全量核对
- 保护签名密钥：Payment API Secret 不得出现在日志或暴露给未授权人员
- 关注限流：大批量拉取时控制并发与请求频率
- 差异闭环：为无法自动匹配的记录建立人工复核与补单流程