版权声明：本 Skill 内容来源于上海汇付支付有限公司官方开放平台文档，版权归属上海汇付支付有限公司。如有疑问可咨询汇付支付客服：400-820-2819 / cs@huifu.com
Source: Official Open Platform documentation of Shanghai Huifu Payment Co., Ltd.
Copyright: Shanghai Huifu Payment Co., Ltd.
统一收银台 - 查询、关单与对账
托管交易支付状态查询 + 托管交易关单 + 交易结算对账单查询。
适配版本与复核信息
| 项目 | 内容 |
|---|---|
| Skill 版本 | 1.1.0 |
| 当前适配 SDK | dg-java-sdk 3.0.34 |
| 最后复核日期 | 2026-04-08 |
| 官方文档来源 | 汇付开放平台托管支付查询/关单/对账接口文档、Java SDK 文档、异步消息说明 |
运行依赖与凭据边界
本 Skill 依赖 huifu-dougong-hostingpay-base 提供公共运行时。凭据使用规则与存放边界见 credential-boundary.md。
前置依赖：首次接入请先阅读 huifu-dougong-hostingpay-base 完成 SDK 初始化。
进入本 Skill 前先确认：上游下单侧已经沉淀
req_date、req_seq_id、party_order_id、hf_seq_id等定位键；具体来源和保留策略见 客户前置准备清单。
官方文档补充约束：托管产品文档明确建议在关键业务环节通过反查接口确认非终态订单状态；对账单能力也要求先在控台配置对账文件生成后再查询下载。
协议规则入口
语言适配入口
这份 Skill 的查询键、状态字段、关单约束和对账字段，都是语言无关的。
具体语言怎么初始化和发请求，先看这里：
触发词
- "托管交易查询"、"收银台订单查询"、"托管订单状态"、"查询托管支付结果"
- "托管关单"、"收银台关单"、"关闭托管订单"、"取消托管订单"
- "托管对账单"、"托管对账"、"收银台对账单"、"结算对账"
场景路由
| 用户意图 | 场景 | 详细说明 |
|---|---|---|
| 查询订单支付状态 | 托管交易查询 | 见 payment-status-query.md |
| 关闭未支付订单 | 托管交易关单 | 见 trade-close.md |
| 查询对账单 | 交易结算对账单查询 | 见 reconciliation.md |
汇付 API 端点
| 场景 | API 路径 | 请求方式 |
|---|---|---|
| 交易查询 | v2/trade/hosting/payment/queryorderinfo | POST |
| 交易关单 | v2/trade/hosting/payment/close | POST |
| 对账单查询 | v2/trade/check/filequery | POST |
通用架构
接口层
|- 接收查单、关单、对账请求
|- 校验查询键、原交易流水和账单日期
业务逻辑层
|- 按场景组装查询、关单、对账报文
|- 调用对应语言 SDK 或 HTTP 客户端
+- 输出订单状态、关单状态和账单下载结果
下面出现的 SDK Request 类名，是 Java 适配层的写法。
如果你不是 Java 项目，参数结构仍按本 Skill 的协议字段来实现。
SDK Request 类对照
| 场景 | SDK Request 类 |
|---|---|
| 交易查询 | V2TradeHostingPaymentQueryorderinfoRequest |
| 交易关单 | V2TradeHostingPaymentCloseRequest |
| 对账单查询 | V2TradeCheckFilequeryRequest |
查询请求参数摘要
| 参数 | setter | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| reqDate | setReqDate() | String(8) | Y | 本次查询的请求日期 |
| reqSeqId | setReqSeqId() | String(64) | Y | 本次查询的请求流水号 |
| huifuId | setHuifuId() | String(32) | C | 商户号；不填时必填 partyOrderId |
| orgReqDate | setOrgReqDate() | String(8) | C | 原交易的请求日期；不填时必填 partyOrderId |
| orgReqSeqId | setOrgReqSeqId() | String(64) | C | 原交易的请求流水号；不填时必填 partyOrderId |
| partyOrderId | setPartyOrderId() | String(64) | C | 商户订单号；不填时必须提供 huifuId + orgReqDate + orgReqSeqId |
完整字段说明见 payment-status-query.md
查询返回参数摘要
| 参数 | 类型 | 说明 |
|---|---|---|
| resp_code | String(8) | 查询接口受理返回码；仍需继续看 order_stat、trans_stat、close_stat |
| trans_stat | String(1) | 交易状态：P=处理中、S=成功、F=失败、I=初始（罕见） |
| trans_amt | String(14) | 交易金额 |
| org_req_seq_id | String(128) | 原交易请求流水号 |
| org_hf_seq_id | String(128) | 汇付全局流水号 |
| order_stat | String(1) | 预下单状态：1=已支付、2=支付中、3=已退款、4=处理中、5=失败、6=部分退款 |
| close_stat | String(1) | 关单状态：P=处理中、S=成功、F=失败 |
| ref_amt | String(14) | 可退金额（元） |
| pay_type | String(16) | 交易类型（返回字段名固定为 pay_type，不要按其他接口习惯改成 trans_type） |
| goods_desc | String(40) | 商品描述 |
| is_div | String(1) | 是否分账交易 |
渠道扩展报文与扩展对象（
wx_response、alipay_response、unionpay_response、dy_response、quick_online_response、bank_extend_param、trans_fee_allowance_info、fee_formula_infos）见 payment-status-query.md
关单请求参数摘要
| 参数 | setter | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| reqSeqId | setReqSeqId() | String(64) | Y | 本次关单的请求流水号 |
| reqDate | setReqDate() | String(8) | Y | 本次关单的请求日期 |
| huifuId | setHuifuId() | String(32) | Y | 商户号 |
| orgReqDate | setOrgReqDate() | String(8) | Y | 原交易的请求日期 |
| orgReqSeqId | setOrgReqSeqId() | String(64) | Y | 原交易的请求流水号 |
完整字段说明见 trade-close.md
关单返回参数摘要
| 参数 | 类型 | 说明 |
|---|---|---|
| resp_code | String(8) | 关单接口受理返回码；仍需继续看 close_stat、org_trans_stat |
| close_stat | String(1) | 关单状态：P=处理中、S=成功、F=失败 |
| org_trans_stat | String(1) | 原交易状态：P=处理中、S=成功、F=失败 |
异步回调参数、官方未明确列出的回调地址字段争议与示例说明见 trade-close.md
trans_stat=P 轮询策略
当查询返回 trans_stat=P（处理中）时，启动轮询：
- 间隔：5 秒
- 最大次数：30 次
- 总超时：150 秒
- 超时处理：记录异常日志并人工介入，不要自动关单
int maxRetries = 30;
for (int i = 0; i < maxRetries; i++) {
Map<String, Object> resp = BasePayClient.request(queryRequest, false);
String stat = (String) resp.get("trans_stat");
if (!"P".equals(stat)) break; // 非处理中，退出轮询
Thread.sleep(5000);
}
关单异步通知参数
| 参数 | 类型 | 说明 |
|---|---|---|
| resp_code | String(8) | 业务响应码 |
| huifu_id | String(32) | 商户号 |
| org_req_date | String(8) | 原交易请求日期 |
| org_req_seq_id | String(64) | 原交易请求流水号 |
| org_trans_stat | String(1) | 原交易状态 |
| close_stat | String(1) | 关单状态：S=成功、F=失败 |
使用场景说明
交易查询
- 用户支付后页面未跳转，需确认支付结果
- 收到异步通知后做二次确认
- 定时轮询处理中（trans_stat=P）的订单
交易关单
- 用户长时间未支付，主动关闭订单
- 业务逻辑需要取消订单
- 防止用户在关单前支付导致资金问题
对账单查询
- 查询交易/结算/分账/出金/用户结算等对账文件
- 接口支持 1 年内账单下载；控台下载当前口径暂未限制时间范围
- 对账文件按 T+1 / D+1 跑批生成；最新产品介绍口径建议交易/分账文件
12:00后下载，出金对账单10:30跑批后一小时，结算对账单17:00跑批后一小时 - 对账单查询对外请求字段应直接保持
file_date和bill_type；不要按中文释义改成bill_date、generate_date或file_type
常见错误与排查
| 错误码 | 场景 | 说明 | 排查方法 |
|---|---|---|---|
| 00000000 | 查询/关单 | 处理成功 | - |
| 00000100 | 关单 | 交易处理中 | 等待异步通知确认最终状态 |
| 10000000 | 查询/关单 | 无效参数 | 检查必填字段格式 |
| 99010003 | 查询/关单 | 交易不存在 | 检查 org_req_date 和 org_req_seq_id 是否正确 |
| 30000001 | 关单 | 原交易已终态 / 关单已终态 | 已支付订单走退款流程 |
| 99999999 | 查询/关单 | 系统异常 | 稍后重试 |
| - | 对账单 | file_details 为空 | 查看 task_details 的 task_stat，S 且为空代表无交易记录 |
注意事项
- 查询接口支持
party_order_id单独查询；关单仍必须提供原交易的org_req_date和org_req_seq_id - 关单后用户将无法再对该订单进行支付
- 已支付成功的订单无法关单，只能走退款流程（见 huifu-dougong-hostingpay-cashier-refund）
- 建议在收到异步通知后调用查询接口做二次确认
- 关单前建议先调用查询接口确认订单状态，避免关闭已支付订单
- 如果用户在关单请求发出的同时完成了支付，以最终交易状态为准
- 对账单查询通常返回一个下载链接；文件通常是 zip 包内含 csv，但结算资金对账单模板为 xlsx，补生成场景的
file_date需填交易日期+1天，且对外字段名应直接保持file_date - 对账单查询的请求字段名必须保持
bill_type；除非用户现有接口已经发布并要求兼容，否则不要再设计file_type -> bill_type的中间映射
快速接入代码示例见 quickstart.md。
版权声明与联系方式见 copyright-notice.md