前言¶
在業務里加支付寶收款，常見難點不是「會不會調一個接口」，而是產品選型：當面付、訂單碼、App 支付、JSAPI、H5、PC 網站、預授權、商家扣款各自對應不同 API 與文檔頁。若只靠模型憑記憶寫代碼，容易選錯產品、漏讀異步通知與驗籤規範，上線前也很難系統自檢。
下面介紹 SkillHub 上的社區 Skill alipay-payment-integration（座標 @user_944a3ade/alipay-payment-integration-v3）。它把支付寶開放平臺多場景接入整理成可執行的集成流程：按業務場景路由到對應產品與在線文檔，並約束 Agent 用 curl 拉取最新文檔後再回答或寫代碼。
這是什麼¶
alipay-payment-integration 是一份面向 Agent 的 支付寶開放平臺支付產品接入最佳實踐 Skill，發佈者爲 SkillHub 用戶 user_944a3ade，來源爲 community，分類爲 dev-programming，當前版本 1.0.0。Skill 包內說明材料與支付寶開放平臺文檔體系對齊（包內可見 skills-Alipay.alipay-payment-integration-master 目錄）。
Skill 頁標註 requires_api_key=false，表示安裝與觸發本 Skill 本身不依賴額外 API Key；實際支付接入仍須在支付寶開放平臺完成應用創建、密鑰與產品開通等配置。
核心功能¶
以下內容來自 Skill 包內 SKILL.md 與 references/checklist.md，爲已覈實能力摘要。
場景路由與產品選型¶
Skill 提供接入路由表與快速決策樹，按線下/線上、押金、週期扣款等分支，映射到推薦產品與核心 API，例如：
| 場景 | 推薦產品 | 核心 API |
|---|---|---|
| 用戶出示付款碼，商家掃碼收款 | 當面付 | alipay.trade.pay |
| 商家生成二維碼，用戶掃碼付款 | 訂單碼支付 | alipay.trade.precreate |
| 手機瀏覽器 H5 喚起支付寶 | 手機網站支付 | alipay.trade.wap.pay |
| 電腦瀏覽器跳轉收銀臺 | 電腦網站支付 | alipay.trade.page.pay |
| 支付寶小程序內支付 | JSAPI 支付 | alipay.trade.create + my.tradePay |
| 原生 App 內支付 | App 支付 | alipay.trade.app.pay |
| 押金凍結、信用住等 | 預授權支付 | alipay.fund.auth.order.app.freeze |
| 週期扣款、自動續費 | 商家扣款 | 支付並簽約 + 後續 alipay.trade.pay |
另有「場景關鍵詞匹配」表，便於在用戶說「H5 支付」「付款碼」「連續包月」等表述時路由到對應產品。
在線文檔訪問規範¶
Skill 明確要求：支付寶支付產品文檔爲在線動態鏈接，接入前須先讀對應產品文檔。訪問方式示例爲用 curl 拉取 CMS 頁面，並對文檔內子鏈接遞歸訪問，以獲取產品介紹、接入準備、接口參數與示例。
集成流程約束分爲三步：
- 集成信息收集：閱讀 SDK 選型與加簽方式文檔（推薦 RSA2 / SHA256WithRSA）。
- 獲取產品集成文檔：按路由到的產品閱讀快速接入、接口列表、異步通知與注意事項，並閱讀接入規範與公共錯誤碼說明。
- 集成校驗：開發與上線前按校驗清單核對簽名驗籤、異步通知、異常處理等。
安全紅線與限制¶
Skill 列出支付接入安全紅線，包括：私鑰不得存客戶端、不得寫日誌、不得進公共倉庫；前臺同步結果不可信；未確認結果前不得要求用戶重付；異步通知必須先驗籤。
明確限制包括：不支持商家分賬產品接入；商家扣款僅支持週期性扣款模式，用戶主動免密支付場景暫不支持；測試階段建議優先使用沙箱網關 https://openapi-sandbox.dl.alipaydev.com/gateway.do，正式環境爲 https://openapi.alipay.com/gateway.do。
集成校驗清單¶
包內 references/checklist.md 提供密鑰與安全、異步通知、支付結果處理、退款、上線前切換等校驗項，並附帶集成結果校驗模板（通過 / 不通過 / 部分通過 / 不適用），便於 Agent 在集成後期輸出結構化自檢結論。
安裝與啓用¶
SkillHub 頁面給出的安裝提示爲：讓 Agent 按 SkillHub 安裝說明 安裝座標 @user_944a3ade/alipay-payment-integration-v3。
若本機已有 skillhub CLI，可先確認版本：
command -v skillhub && skillhub --version
未安裝時可按官方腳本安裝（完整安裝或僅 CLI，見安裝文檔第一節）。安裝技能時 必須 用 --dir 指向當前 Agent 的 skills 目錄，否則默認裝到 ./skills/ 可能不會被識別。
skillhub install alipay-payment-integration-v3 --namespace user_944a3ade --dir <skills 目錄>
常用 Agent 的 skills 目錄（來自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
也可將下列提示詞發給支持 Skill 的 AI 客戶端，由 Agent 按安裝文檔完成安裝：
請根據 https://skillhub.cn/install/skillhub.md，安裝 `@user_944a3ade/alipay-payment-integration-v3`。
安裝完成後，按所用客戶端要求重啓或刷新技能列表，使 Skill 生效。
典型用法¶
Skill 在 description 中聲明的觸發場景包括：用戶提到「接入支付寶」「集成支付寶支付」「對接支付」「支付寶收款」「H5 支付」「小程序支付」「預授權」「付款碼」「週期扣款」「自動續費」等。
典型工作方式如下。
- 用戶描述業務場景（或關鍵詞模糊時，Agent 使用 Skill 內「澄清話術」追問線下/線上、App、小程序、押金、訂閱等）。
- Agent 根據路由表選定產品與核心 API，用
curl訪問對應在線文檔 URL（Skill 內附有當面付、訂單碼等各產品文檔鏈接示例）。 - 在編寫代碼或回答接入問題前，完成 SDK 選型、加簽方式、接入規範與異步通知等必讀文檔的閱讀。
- 集成後期或上線前，按
references/checklist.md輸出校驗模板，標註風險項。
文檔拉取示例（來自 Skill 正文）：
# 獲取當面付主文檔
curl -sL "https://ideservice.alipay.com/cms/site/0izcu3"
適用場景與注意¶
適合誰
- 需要在 Cursor、Claude Code、Codex 等 Agent 環境中做支付寶多場景接入的開發者。
- 希望 Agent 先讀官方在線文檔再生成代碼，而不是僅憑靜態片段猜參數的團隊。
- 希望在聯調與上線前用統一清單檢查驗籤、異步通知與資損相關項的項目。
使用注意
- Skill 強調文檔動態更新，每次接入應以
curl獲取的當前頁面爲準；校驗清單結果僅供參考，最終以 支付寶開放平臺 最新文檔爲準。 - 社區 Skill 在 SkillHub 上的評分爲 100000，下載量 1031（以 SkillHub 頁面抓取數據爲準）；與支付相關的密鑰、APPID、網關環境須由開發者自行在開放平臺配置，Skill 不替代合規與安全審計。
- 商家扣款產品 Skill 說明提及 2026 年 4 月 2 日產品升級，僅覆蓋最新版本接入路徑；分賬、部分扣款場景需另查官方文檔或聯繫支付寶技術支持。
結尾¶
alipay-payment-integration 把「選哪條支付產品線、先讀哪些在線文檔、上線前查哪些項」寫成 Agent 可 follow 的流程，適合作爲支付寶接入時的常駐 Skill。官方 SkillHub 頁面與 API 入口：
- https://www.skillhub.cn/skills/user_944a3ade/alipay-payment-integration-v3
- https://api.skillhub.cn/user_944a3ade/alipay-payment-integration-v3
