Huifu Pay Integration — 汇付支付集成

汇付支付集成 版权声明 本 Skill 包中的汇付支付、斗拱支付接口资料整理自上海汇付支付有限公司官方开放平台与官方产品文档；原始文档及其更新维护权归汇付支付官方所有。本 Skill 包仅作技术学习交流与接口集成辅助使用，详细口径见 references/shared-copyright-notice.md。

目标：只读取当前场景必须的 3-5 份本地文档；优先暴露缺口和能力边界，不拼凑看似完整但当前链路不支持的方案；PHP 一旦需要落代码，默认体现官方 dg-php-sdk 落地。

用户可读路由树 这段用于先让用户看懂“当前问题该走哪条接入路径”；实际执行时仍按下方 最少澄清规则、检查点机制、执行工作流 和 输出模板 裁决。 树中的 .md 文件默认都位于 references/ 目录。

汇付支付接入 ├─ 还没确定产品线 │ └─ 先读 shared-overview.md，再判断聚合支付 / 托管支付 / checkout-js ├─ 聚合支付：服务端直接下单、扫码 / 付款码、小程序支付 │ ├─ 首次接入：aggregation-quickstart.md → aggregation-customer-preparation.md → aggregation-base.md │ ├─ 下单：aggregation-order.md → 按渠道补 aggregation-order-method-.md │ ├─ 查询 / 关单 / 对账：aggregation-query.md │ ├─ 退款 / 退款查询：aggregation-refund.md │ └─ PHP 落地：aggregation-php-adapter.md → aggregation-query-php-scenarios.md ├─ 托管支付：项目制预下单、H5 / PC 收银台、小程序预下单 │ ├─ 首次接入：hostingpay-quickstart.md → hostingpay-customer-preparation.md → hostingpay-base.md │ ├─ 预下单：hostingpay-preorder.md → 按端形态补 hostingpay-preorder-.md │ ├─ 查询 / 关单 / 对账：hostingpay-query.md │ ├─ 退款 / 退款查询：hostingpay-refund.md │ └─ PHP 落地：hostingpay-php-adapter.md → hostingpay--php-scenarios.md ├─ checkout-js：商户自有页面内嵌支付组件 │ ├─ 前置能力：必须已有托管预下单 │ ├─ 页面接入：checkout-js.md → checkout-js-readme.md │ ├─ 预下单契约：checkout-js-create-preorder-contract.md │ └─ 最终确认：checkout-js-callback-and-confirmation.md → hostingpay-query.md / hostingpay-async-webhook.md └─ 高风险或缺口 ├─ 要生产代码但缺真实参数：先补 project_id / notify_url / sys_id / 商户号等 ├─ 当前技术栈没有模板：只给阅读路径，不现场编造模板 └─ 文档与 SDK 口径冲突：先触发硬检查点

什么时候使用 第一次接入汇付支付，还不确定该走聚合支付、托管支付还是前端 checkout 已经知道要接汇付，但还没判断清楚当前阶段是初始化、下单 / 预下单、查询 / 关单 / 对账、退款还是前端页面接入 用户直接提到“微信小程序支付”“支付宝正扫”“付款码支付”“二维码支付”“H5/PC 收银台”“checkout-js”“查单”“退款”等意图，需要先路由到正确 reference 需要先判断 Java、PHP、Browser / JS 哪条实现路径当前可落地

什么时候不要使用 用户已经明确指定某份具体文档，只需要读取那一份 用户已经进入某个专题文档，当前问题只和该专题内的参数、返回字段或代码示例有关 用户已经明确指定某个官方 PHP SDK request 类、已有业务专题文档或具体接口页，只需要读取那一份

决策优先级 先判断当前问题是否已经落到具体专题文档；如果已经落到专题，不再回到总技能 再判断产品线：聚合支付、托管支付，还是商户前端 checkout 再判断当前能力是否被当前技术栈覆盖；如果不覆盖，立即显式说明，不继续把用户引到错误模板 再判断阶段：首次接入、初始化、下单 / 预下单、查询 / 关单 / 对账、退款、前端支付组件 最后判断渠道或端形态：微信 / 支付宝 / 银联、小程序、H5 / PC、付款码、二维码

最少澄清规则 如果用户已经明确给出“产品线 + 阶段 + 技术栈”，不要重复追问，直接给阅读顺序 如果缺少的信息不会影响主路由，不追问，先给主路径 如果用户已经明确说“已完成初始化”“已完成托管预下单”“已经能查单”，跳过 -quickstart.md 和 -base.md，直接进入当前阶段文档 如果用户已经明确说“已完成托管预下单和查单，现在只接 checkout-js”，不要再把 hostingpay-preorder.md、hostingpay-query.md 列为本轮主阅读文档；只补 checkout-js 专题和 hostingpay-async-webhook.md 只有在以下情况才追问： 无法判断是聚合支付还是托管支付 无法判断是服务端接入还是前端 checkout 用户指定 PHP，但当前阶段在 PHP 上没有现成覆盖 文档与 SDK 口径冲突

检查点机制 只允许两类检查点：软检查点 和 硬检查点。

软检查点 软检查点不等待用户回复，触发后直接继续给主路径。 触发条件： 用户已经声明某些前置阶段完成，本轮需要主动跳过 -quickstart.md、*-base.md 或已完成的主文档 当前回答会明确排除一整条相邻路径，例如排除聚合支付、排除前端 checkout、排除非官方自维护 PHP client 需要提醒某个依赖关系，但不影响继续路由，例如 checkout-js 依赖托管预下单和最终结果确认闭环 输出要求： 先用 1 句写清当前判断 再用 1 句写清本轮主动跳过什么 不追加开放式追问，直接继续给阅读顺序或结论

硬检查点 硬检查点必须等待用户确认后再继续。 只在以下情况触发： 无法区分聚合支付、托管支付、checkout 三条主链路，继续回答会把用户带到不同文档集合 无法区分服务端接入、前端页面接入、最终状态确认三种职责，继续回答会导致读错阶段文档 用户要求“直接给代码 / 现成模板”，但当前组合无模板，且存在两条以上可行回退路径，例如“切到 Java 主链路”或“保持当前技术栈只看协议级路径” 用户想单独推进 checkout-js、只看前端回调、或只做页面集成，但是否已具备托管预下单和最终查单 / 异步通知闭环还不明确；即使用户要求“不用问”“直接给路线”“最省事”，也必须触发硬检查点 用户要求“可直接联调 / 可上线 / 生产可用”的代码，但缺少 project_id、notify_url、sys_id、渠道标识、商户号等关键真实值，继续输出会制造伪完整代码 本地 SDK 源码与当前文档口径冲突，且冲突点属于请求头、签名、版本、能力覆盖这类高风险事实 硬检查点输出要求： 第一行必须直接写 硬检查点 先写 当前判断 再写 为什么不能直接继续 最后只问 1 个最短确认问题 未得到确认前，不继续输出完整阅读顺序、代码骨架或技术栈切换方案 对 checkout-js 先决能力未确认的硬检查点，不输出安装步骤、前端接法或文档阅读顺序

以下情况不要触发硬检查点： 用户只问文档阅读顺序，不要求代码，且主路由已足够明确 缺少的信息不会改变主链路，只会影响后续真实参数填充 当前只能给出唯一正确结论，不存在需要用户二选一的分叉

默认裁决规则 用户一旦提到 H5 / PC 收银台、project_id、checkout-js、createPreOrder、商户自有