跳转到主要内容

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 对账能力支持商户通过 API 按时间范围批量拉取订单明细。后续将陆续增加其他类型的订单列表查询，以及资金流水查询能力。 常见使用场景包括：
  • 日终将 Gate Pay 收单、下发数据与内部账本核对
  • 对接 BI 或数据仓库，定时同步订单明细
  • 结合订单号、状态筛选，排查单笔或批量异常
  • 作为支付/出款回调的兜底数据源，确认最终状态

​
前置条件

在接入对账能力之前，需先完成以下准备工作：
  1. 创建应用：在商户后台创建 GatePay 应用
  2. 获取 ClientId：获取用于 API 认证的 ClientId
  3. 配置签名密钥：配置请求签名所需的密钥
  4. 配置回调地址：设置用于接收异步通知的回调接口地址
详细配置说明请参见 接入总览 和 认证与安全。

​
对账接入步骤

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

按创建时间范围分页查询收款订单，支持按订单类型、状态、支付方式等条件筛选。 请求接口： 
GET /payment/open/v1/pay/order/list
该接口可获取指定时间窗口内的收款订单明细，包括订单号、金额、状态、手续费及链上信息等。完整入参、出参见 API 参考。

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

按创建时间范围分页查询下发订单，支持按渠道、订单状态、审批状态等条件筛选。 请求接口： 
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 工具补充字段

​
请求签名与校验

所有对账请求都必须使用 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 不得出现在日志或暴露给未授权人员
  • 关注限流：大批量拉取时控制并发与请求频率
  • 差异闭环：为无法自动匹配的记录建立人工复核与补单流程

​
相关文档