统一收银台 — 查询、关单与对账

托管交易支付状态查询 + 托管交易关单 + 交易结算对账单查询。

前置依赖：首次接入请先阅读 dougong-hostingpay-pay-base 完成 SDK 初始化。

进入本 Skill 前先确认：上游下单侧已经沉淀 req_date、req_seq_id、party_order_id、hf_seq_id 等定位键；具体来源和保留策略见 客户前置准备清单。

官方文档补充约束：托管产品文档明确建议在关键业务环节通过反查接口确认非终态订单状态；对账单能力也要求先在控台配置对账文件生成后再查询下载。

触发词

• "托管交易查询"、"收银台订单查询"、"托管订单状态"、"查询托管支付结果"
• "托管关单"、"收银台关单"、"关闭托管订单"、"取消托管订单"
• "托管对账单"、"托管对账"、"收银台对账单"、"结算对账"

场景路由

汇付 API 端点

通用架构

HFPayController (@RestController, /hfpay)
    ├── POST /queryorderinfo  → hostingPayService.queryOrderInfo(req)
    ├── POST /closeOrder      → hostingPayService.closeOrder(req)
    └── POST /checkFileQuery  → hostingPayService.checkFileQuery(req)

HostingPayService (@Service)
    ├── queryOrderInfo()  → V2TradeHostingPaymentQueryorderinfoRequest → BasePayClient.request()
    ├── closeOrder()      → V2TradeHostingPaymentCloseRequest          → BasePayClient.request()
    └── checkFileQuery()  → V2TradeCheckFilequeryRequest               → BasePayClient.request()

SDK Request 类对照

查询请求参数摘要

完整字段说明见 payment-status-query.md

查询返回参数摘要

渠道扩展报文与扩展对象（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

关单请求参数摘要

完整字段说明见 trade-close.md

关单返回参数摘要

异步回调参数、官方未明确列出的回调地址字段争议与示例说明见 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);
}

关单异步通知参数

使用场景说明

交易查询

• 用户支付后页面未跳转，需确认支付结果
• 收到异步通知后做二次确认
• 定时轮询处理中（trans_stat=P）的订单

交易关单

• 用户长时间未支付，主动关闭订单
• 业务逻辑需要取消订单
• 防止用户在关单前支付导致资金问题

对账单查询

• 查询交易/结算/分账/出金/用户结算等对账文件
• 接口支持 1 年内账单下载；控台下载当前口径暂未限制时间范围
• 对账文件按 T+1 / D+1 跑批生成；最新产品介绍口径建议交易/分账文件 12:00 后下载，出金对账单 10:30 跑批后一小时，结算对账单 17:00 跑批后一小时
• 对账单查询对外请求字段应直接保持 file_date 和 bill_type；不要按中文释义改成 bill_date、generate_date 或 file_type

常见错误与排查

注意事项

1. 查询接口支持 party_order_id 单独查询；关单仍必须提供原交易的 org_req_date 和 org_req_seq_id
2. 关单后用户将无法再对该订单进行支付
3. 已支付成功的订单无法关单，只能走退款流程（见 dougong-hostingpay-cashier-refund）
4. 建议在收到异步通知后调用查询接口做二次确认
5. 关单前建议先调用查询接口确认订单状态，避免关闭已支付订单
6. 如果用户在关单请求发出的同时完成了支付，以最终交易状态为准
7. 对账单查询通常返回一个下载链接；文件通常是 zip 包内含 csv，但结算资金对账单模板为 xlsx，补生成场景的 file_date 需填交易日期 +1 天，且对外字段名应直接保持 file_date
8. 对账单查询的请求字段名必须保持 bill_type；除非用户现有接口已经发布并要求兼容，否则不要再设计 file_type -> bill_type 的中间映射

快速接入代码示例见 quickstart.md。