汇付支付集成

集成挑战

在集成汇付支付时，开发者常面临多产品线选择、接口复杂性和安全规范遵守等具体问题。汇付支付提供聚合支付、托管支付和 checkout-js 等产品线，每种产品线有独立的接口、SDK 和业务规则，导致初次接入或扩展存量系统时决策困难。例如，开发者可能无法明确区分聚合支付（适合快速交易）和托管支付（适合分账场景）的适用条件，或混淆服务端与前端接入的职责。此外，接口字段众多、嵌套深，需处理 sign 签名、验签、幂等更新和支付终态确认，且调试配置不当可能泄露私钥等敏感信息。多端适配进一步增加复杂度，如 Java、PHP、Python SDK 的初始化顺序差异，或 checkout-js 前端回调非终态的误解。

技能工作机制

本技能通过结构化流程帮助开发者高效集成汇付支付，核心能力与关键步骤如下：

执行流程与精确路由

技能首先执行五步流程：识别产品线、技术栈等维度；检查硬检查点（如无法区分接入方式时强制提问）；从 references/ 中选择 3-5 份文档（如聚合下单选 aggregation-order.md）；输出方案卡或回归检查；最后应用签名、幂等规则。关键设计包括：

• 硬检查点：在歧义或缺失信息时停止生成，例如用户要求可运行代码但环境不唯一时，首行输出 🔴 CHECKPOINT · HARD STOP 并只问一个最高优先级问题。
• 字段管理：提供完整字段目录，区分 wire 路径（如 JSON 原始键）与解码后路径（如 trade_no），避免使用占位描述；链接按用途处理，坏锚点如 #业务返回码 映射到公共返回码全集。
• 安全边界：私钥、系统号必须从服务端配置读取，禁止写入前端或日志；PHP SDK 必须在加载前固定 DEBUG=false，避免官方 Demo 的调试日志泄露 MerConfig。

核心能力与适配

技能覆盖从快速接入到上线检查的全流程：

• 聚合支付：支持下单、查询、退款等，如 notify_url 同时处理正扫和反扫通知，需按 trade_type 分场景解析。
• 托管支付：包括预下单、拆单支付查询，对接 checkout-js 时需确认支付通知验签和幂等。
• SDK 适配：按语言选择参考文档（如 Java 用 aggregation-java-adapter.md），确保使用官方 SDK Request（如 dg-lightning-sdk 1.0.5），不得手写 HTTP 客户端绕过签名。
• 本地沙箱：仅验证协议闭环和状态机，不模拟真实商户权限或生产费率，冻结的合同文件为历史证据不可更改。

关键步骤示例

集成时需遵循：1) 初始化检查项目中 SDK 版本和请求头；2) 根据交易类型补全字段（如聚合退款参考 aggregation-refund.md 和 payment-complete-field-catalog.md）；3) 支付终态通过通知验签（先验签再校验金额）和查单补偿确认，禁止伪造通知；4) 上线前检查 TLS 证书链和 skill_source 默认值（如仅本 Skill 使用 hfps/1.3.4）。

适用边界与注意点

本技能专注于支付交易集成，有明确限制：

• 不处理进件：商户进件、图片资料审核等需使用独立 $huifu-merchant-onboarding 技能，避免从本 Skill 误读文档。
• 支付终态确认：同步受理、jump_url、浏览器回跳或前端 callback 均非终态，必须依赖服务端通知验签和查询接口（如 aggregation-query-payment-query.md）。
• 安全红线：生产商户号、RSA 密钥等仅存于服务端，示例代码中禁止暴露；PHP 联调时必须拒绝官方 Demo 入口（如 BsPayDemo/loader.php）以防 DEBUG 日志泄漏。
• 能力缺口报告：若官方 SDK 缺少特定 Request（如某些端形态），需明确报告而不手写 HTTP 补位。
• 沙箱局限：本地测试不验证通道费率、风控或生产准入，仅作为逻辑验证辅助。

集成时应严格遵循指南，确保每一步都符合硬检查点和安全规范，从而构建可靠的支付系统。