汇付托管支付接口

集成汇付 SDK 实现托管支付的完整链路：预下单 → 订单查询 → 退款。

引导词

当开发者提到以下关键词时，本技能被触发：

预下单、支付预下单、托管支付、创建支付订单
订单查询、支付查询、查询订单、支付状态
退款、支付退款、订单退款、refund
/hfpay/preOrder、/hfpay/queryorderinfo、/hfpay/htRefund

前置检查

在编写代码之前，必须完成以下检查：

步骤1：检查 SDK 依赖

检查项目 pom.xml 中是否包含 dg-java-sdk 依赖：

<dependency>
    <groupId>com.huifu.bspay.sdk</groupId>
    <artifactId>dg-java-sdk</artifactId>
    <version>3.0.34</version>
</dependency>

步骤2：安装依赖（如未安装）

在 pom.xml 中添加上述依赖后执行：

mvn clean install

步骤3：验证导入

确认以下核心类可正常导入：

com.huifu.bspay.sdk.opps.core.BasePay
com.huifu.bspay.sdk.opps.core.config.MerConfig
com.huifu.bspay.sdk.opps.client.BasePayClient
com.huifu.bspay.sdk.opps.core.utils.DateTools
com.huifu.bspay.sdk.opps.core.utils.SequenceTools

各场景所需的 Request 类：

场景	Request 类
预下单	`V2TradeHostingPaymentPreorderH5Request`
订单查询	`V2TradeHostingPaymentQueryorderinfoRequest`
退款	`V2TradeHostingPaymentHtrefundRequest`

只有完成以上前置检查后，才能继续按照 reference 目录中的示例代码进行开发。

javax / jakarta 命名空间说明

示例代码使用 javax.annotation 和 javax.validation 命名空间（适用于 Spring Boot 2.x）。如果项目使用 Spring Boot 3.x + JDK 17/21，需将 javax 替换为 jakarta：

Spring Boot 2.x (javax)	Spring Boot 3.x (jakarta)
`javax.annotation.PostConstruct`	`jakarta.annotation.PostConstruct`
`javax.validation.constraints.NotBlank`	`jakarta.validation.constraints.NotBlank`

场景路由

根据用户意图选择对应场景：

用户意图	场景	接口路径	详细说明
创建支付订单	预下单	`POST /hfpay/preOrder`	见 SCENARIOS.md #预下单
查询订单状态	订单查询	`POST /hfpay/queryorderinfo`	见 SCENARIOS.md #订单查询
对已支付订单退款	退款	`POST /hfpay/htRefund`	见 SCENARIOS.md #退款

根据用户描述的场景，读取 SCENARIOS.md 中对应章节获取请求参数、响应参数和实现细节。

通用架构设计

三个场景共享同一套分层架构和商户配置：

HuifuConfig (@Configuration)
    └── @PostConstruct initSdk() — 初始化 SDK（仅应用启动时执行一次）

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

HostingPayService (@Service, 构造器注入 ObjectMapper)
    ├── preOrder()       → 组装请求 → BasePayClient.request() → 返回响应
    ├── queryOrderInfo() → 组装请求 → BasePayClient.request() → 返回响应
    └── htRefund()       → 组装请求 → BasePayClient.request() → 返回响应

DTO层（含 @NotBlank 校验）
    ├── HostingPayPreOrderReq
    ├── HostingPayQueryOrderReq
    └── HostingPayHtRefundReq

交易状态枚举（通用）

状态码	含义	建议处理方式
P	处理中	等待异步通知或轮询查询
S	交易成功	执行业务成功逻辑
F	交易失败	提示用户重新发起或联系客服

代码示例

详见 reference 目录下的示例代码文件：

huifu-hosting-payment

Install via CLI (Recommended)