name: huifu-pay-integration description: "匯付支付交易整合：用於聚合支付、託管支付、checkout-js、下單、查單、關單、退款、對賬、支付通知、簽名驗籤、請求頭、冪等、交易終態、本地沙箱和支付上線；不用於企業/個人商戶進件、圖片上傳、商戶業務開通、商戶詳情或申請狀態查詢，這些任務使用 huifu-merchant-onboarding。"

7w4.net提供免費和付費技能下載。

匯付支付整合

版權宣告

本 Skill 中的匯付支付資料整理自上海匯付支付有限公司官方開放平臺與官方產品文件；原始文件及其更新維護權歸匯付支付官方所有。僅作技術學習交流與介面整合輔助使用，詳見 references/shared-copyright-notice.md。

執行流程

1. 識別產品線、Endpoint、接入階段、技術棧、端形態、當前目標和是否存量系統。完成標準：這些維度均已唯一確定，極速版產品場景與 V4 API 列舉已分開。
2. 檢查下方硬檢查點；命中時停止生成可執行實現，只問一個最高優先順序問題。完成標準：已記錄命中或未命中的具體理由，SDK 傳輸安全和除錯日誌均已檢查。
3. 從精確路由中選擇 3–5 份 reference。只有使用者同時提出兩個獨立目標時才合併；完整 DTO、響應或巢狀欄位任務必須包含完整欄位目錄。完成標準：每個目標均有一跳可達的原子介面頁、合同定位路徑、實際 JSON/解碼路徑（分別記錄 wire 欄位路徑與 String(JSON) 解碼後路徑）和明確語言 adapter，不使用“對應文件”佔位，也不把官網展示分組當成 wire key；只有官網明確標註“方便文件展示”時才從 wire 路徑移除該分組。
4. 首次接入輸出產品線判斷和方案卡；存量接入輸出新增、保留、人工確認和迴歸檢查。完成標準：請求、前端交接、通知、終態和補償查詢責任均已落到具體元件。
5. 最後應用簽名、驗籤、冪等、終態確認、請求欄位保留和憑據安全規則。完成標準：每項均已檢查，未知合同明確標記並停止生成相應實現。

欄位說明中的連結按其用途處理：完整欄位目錄已將官網 #錨點 / 相對連結解析到各自介面原始頁，並保留相對地址原文；絕對地址保持官網值。已確認的壞錨點使用顯式對映：#業務返回碼 補公共返回碼全集，聚合下單 notify_url 的“非同步返回引數”同時對映正掃、反掃通知引數和通用非同步訊息規範。只有命中本次欄位的規範文件、編碼表或渠道指引才作為外部資料提示。notify_url、jump_url、下載地址、二維碼等裸 URL 示例是執行時值或格式示例，不是預設值、推薦地址或外部資料。

本 Skill 只處理支付交易。企業、個人商戶進件、圖片資料、業務開通、商戶詳情和申請狀態使用 $huifu-merchant-onboarding；不要從本 Skill 讀取進件實現文件。

精確路由

按語言選擇 reference：

• Java：公共矩陣 + 產品線 Java adapter；先核對專案中的實際 SDK 版本和 Request 類。
• PHP：公共矩陣 + 產品線 PHP adapter；保留安全初始化順序，但不得使用會啟用 DEBUG=true 的官方 Demo/Composer loader。
• Python：公共矩陣 + 產品線 Python adapter；不要把 SDK 網路重試解釋成業務重試。
• 前端：checkout-js 只負責展示與前端事件，支付終態仍由服務端確認。

🔴 CHECKPOINT · HARD STOP

命中以下任一情況時，首行輸出 🔴 CHECKPOINT · HARD STOP：硬檢查點。，列出當前判斷和本輪 references，只問一個最高優先順序問題：

1. 無法區分聚合支付、託管支付和 checkout-js。
2. 無法區分服務端接入、前端頁面接入和最終狀態確認。
3. 使用者要求現成可執行程式碼，但當前介面、端形態或回退路徑不唯一。
4. checkout-js 的託管預下單、支付通知驗籤/冪等和查單補償未確認。
5. 使用者要求聯調或生產程式碼，但缺少環境、系統號、產品號、商戶號、RSA 金鑰安全來源、通知地址或必要渠道標識。未顯式配置 skill_source 時使用下述確定性預設值，不因此硬停。
6. 本地 SDK 原始碼與文件在請求頭、簽名、版本或能力覆蓋上衝突。
7. 使用者要求 Java 或 PHP 聯調/生產可執行程式碼，但鎖定的 Lightning Java 1.0.5、通用 Java 3.0.40 或 PHP 2.0.30 仍關閉 TLS 證書鏈、對端或主機名校驗；在經批准的安全製品通過原始碼和錯證書/錯域名測試前不得輸出可上線實現。
8. 使用者要求 PHP 聯調或生產可執行程式碼，但不能證明在載入 SDK、Demo/Composer 配置和呼叫 BsPay::init 之前已將全域性 DEBUG 固定為 false，或仍使用會定義 DEBUG=true 的官方 Demo/Composer 入口。

SDK 安裝、初始化和安全 loader 骨架不因產品線不明而硬停，但不得猜具體業務 Request 或欄位；PHP 骨架必須在載入任何 SDK 檔案前拒絕 DEBUG=true。

支付終態與通知

• 同步受理成功、jump_url、瀏覽器回跳和前端 callback 都不是支付終態。
• 對支付通知先驗籤，再校驗金額、商戶號、訂單號和狀態，最後做冪等更新。
• 通知缺失時使用官方查單補償；不要偽造通知、跳過驗籤或直接改成功。
• 控臺 Webhook 和介面 notify_url 是不同協議，不能混用簽名位置或 ACK。
• 聚合下單的同一個 notify_url 同時承接正掃和反掃兩套通知引數；按 trade_type 分場景解析，不得只實現一套。

請求和憑據

• 保留 Controller/DTO 已接收的 req_date、req_seq_id、金額、商戶號和原交易定位鍵；缺失或非法時報錯，不自行重寫。
• 私鑰、系統號和生產商戶號只能從服務端安全配置讀取，不能寫入前端、日誌、倉庫或回答示例。
• PHP 2.0.30 預設 DEBUG=false，但官方 BsPayDemo/loader.php 與 Composer/BsPayConfig.php 會在初始化前啟用除錯；除錯日誌會包含帶 RSA 私鑰的 MerConfig、完整請求和響應。聯調/生產必須拒絕這些入口，並在載入任何 SDK 檔案前固定 DEBUG=false。
• 未顯式配置 skill_source 時，按當前請求實際載入並參與生成的 Skill 集合取值：僅本 Skill 使用 hfps/1.3.3；支付與進件兩個 Skill 都參與當前請求時使用 hfps/1.3.3;hfms/1.0.0。僅安裝在倉庫但未參與當前請求不計入；順序固定為支付、進件，使用一個英文分號且不加空格。
• 呼叫方顯式提供經確認的 skill_source 合同值時原樣透傳；不得再追加 sys_id。
• 不因方便繞過 SDK 的簽名、驗籤、證書或請求頭路徑。

本地沙箱邊界

本地沙箱僅驗證本地協議閉環、狀態機、冪等、故障注入和報告，不驗證真實商戶許可權、通道、費率、風控、資金結果或生產准入。凍結的 r1–r4 合同和樣例包屬於歷史支付證據，不得因本次 Skill 拆分改名或重算。

輸出要求

回答至少包含：

1. 當前產品線、階段、技術棧和存量判斷。
2. 本輪實際使用的 3–5 份 references。
3. 請求、通知、終態和安全邊界。
4. 缺失資訊、人工確認項和下一步。

不要輸出費率、合規、通道准入或生產失敗責任結論；只整理脫敏升級材料並轉人工確認。

當前版本

這個 Skill 質量不錯，文件組織清晰、內容專業，覆蓋了匯付支付的主要接入場景。優點是安全規則寫得很詳細，能幫你避免常見坑；路由設計合理，找資料不費勁；多語言支援也做得比較全面。不足的地方是對新手不太友好，缺少簡單例子；另外本地測試工具還有些已知問題沒修復。總體來說，這是一個值得信賴的專業級支付整合參考包。