汇付托管支付接口

集成汇付 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 目录下的示例代码文件：

| 文件 | 说明 | |-----|------| | HuifuConfig.java | SDK 配置初始化类（@Configuration + @PostConstruct） | | HFPayController.java | Controller 层（三个接口端点） | | HostingPayService.java | Service 层（三个场景的业务方法） | | HostingPayPreOrderReq.java | 预下单请求 DTO | | HostingPayQueryOrderReq.java | 订单查询请求 DTO | | HostingPayHtRefundReq.java | 退款请求 DTO | | Result.java | 统一响应封装 |

安全规则

严禁在源代码中硬编码商户密钥，必须通过 application.yml 配置并使用环境变量注入
notify_url 和 callback_url 必须替换为实际业务地址，禁止使用任何测试域名
退款操作涉及资金变动，日志中应记录关键参数但避免打印完整密钥信息
hosting_data 中的 project_id 需替换为实际项目 ID

环境变量配置

application.yml 配置示例：

huifu:
  product-id: ${HUIFU_PRODUCT_ID}
  sys-id: ${HUIFU_SYS_ID}
  rsa-private-key: ${HUIFU_RSA_PRIVATE_KEY}
  rsa-public-key: ${HUIFU_RSA_PUBLIC_KEY}
  notify-url: ${HUIFU_NOTIFY_URL}
  refund-notify-url: ${HUIFU_REFUND_NOTIFY_URL}
  hosting:
    project-id: ${HUIFU_PROJECT_ID}
    project-title: ${HUIFU_PROJECT_TITLE}
    callback-url: ${HUIFU_CALLBACK_URL}