前言¶
在业务里加支付宝收款，常见难点不是「会不会调一个接口」，而是产品选型：当面付、订单码、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
