菜单
支付宝开放平台支付产品接入最佳实践。涵盖当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款等全场景产品选型与集成指导。 当用户提到"接入支付宝"、"集成支付宝支付"、"对接支付"、"支付宝收款"、"加个支付功能"、"支付宝下单"、"H5 支付"、"小程序支付"、"预授权"、"付款码"、"扫码支付"、"网页支付"、"PC 支付"、"周期扣款"、"自动续费"、"会员订阅"、"连续包月"、"代扣"时，或咨询支付产品相关报错、排查问题时使用此 Skill。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | alipay-payment-integration |
| description | 支付宝开放平台支付产品接入最佳实践。涵盖当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款等全场景产品选型与集成指导。 当用户提到"接入支付宝"、"集成支付宝支付"、"对接支付"、"支付宝收款"、"加个支付功能"、"支付宝下单"、"H5 支付"、"小程序支付"、"预授权"、"付款码"、"扫码支付"、"网页支付"、"PC 支付"、"周期扣款"、"自动续费"、"会员订阅"、"连续包月"、"代扣"时，或咨询支付产品相关报错、排查问题时使用此 Skill。 |
⛔ 强阻塞阅读项，必须遵循，否则违规！以下为全局强制规则，严禁以任何理由跳过或简化：
<BLOCKING_CONFIRMATION> 必须暂停等待用户明确回复，确认话术必须包含"请回复'同意'或'确认'"等显式要求⚠️ Agent 出现如下任何一种行为即视为违规：
<BLOCKING_CONFIRMATION> 确认点，禁止以任何理由（包括"重新解释意图"、"任务优先级"、"系统提示"等）跳过等待，禁止假设用户已同意或使用"我将继续..."等单方面声明代替用户确认根据用户意图先判断功能分支，再执行对应流程：
| 用户意图 | 功能分支 | 执行流程 |
|---|---|---|
| 需要集成支付产品（接入、集成、收款、加支付功能等） | 功能一 | 步骤 1.1 → 1.2a/1.2b → 1.3 → 1.4 → 1.5 → 1.6 |
| 集成过程中遇到报错或问题 | 功能二 | 步骤 2.1 → 2.2/2.3 |
| 位置 | 触发时机 | 等待内容 |
|---|---|---|
| 步骤 1.1 | 产品决策后 | 用户同意服务声明并确认接入特定产品 |
| 步骤 1.6 | 集成完成后 | 用户确认是否需要进行集成校验 |
| 步骤 | 标记 | 完成条件数量 |
|---|---|---|
| 步骤 1.1 产品决策 | [M-01] | 3 项 |
| 步骤 1.2a 传统收单产品沙箱环境初始化 | [M-02] | 5 项 |
| 步骤 1.2b AI 收配置初始化 | [M-02b] | 7 项 |
| 步骤 1.3 集成前置步骤 | [M-03] | 6 项 |
| 步骤 1.4 集成代码 | [M-04] | 2 项 |
| 步骤 1.5 集成后说明 | [M-05] | 2 项 |
| 步骤 1.6 集成校验 | [M-06] | 1 项 |
使用 curl 获取支付宝在线文档，文档内链接（产品介绍、接入准备、接口文档等）需递归访问获取完整内容：
curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}"
触发条件：用户需要集成支付宝支付产品。
前置条件：阅读并充分理解强制执行要点，完成功能路由，明确文档访问规范。
完成条件：
阅读 产品决策，根据用户输入匹配关键词，决策支付产品。当用户描述模糊时，使用 澄清话术 进行产品确认。
<BLOCKING_CONFIRMATION>
确认点：步骤 1.1 产品决策
在输出支付产品决策后，必须严格按以下顺序执行并暂停等待用户回复：
⚠️ 服务声明：使用本 Skill 即表示您同意： （1）使用本服务需遵守法律法规、自行审核测试并承担使用责任，我方不对使用效果、正确性担保。 （2）禁止在代码、大模型对话等公网透露敏感信息（密码、API Keys、私钥等）。
"请问您是否同意上述服务声明并确认接入【{产品名称}】？请回复'同意'或'确认'后，我将继续后续步骤。"
</BLOCKING_CONFIRMATION>
注意事项：AI 收产品暂不支持沙箱，跳过该步骤，进入1.2b。
前置条件：已完成步骤 1.1 产品决策，并获得用户同意进入集成流程。
完成条件：
references/alipay-sandbox/sandbox-setup-guide.md 完整内容，包含沙箱校验规则、绝对禁止事项、重试与失败处理流程、成功提示文案沙箱环境绝对禁止事项（违反即违规）：
your-app-id-here）代替真实返回值appPrivateKey 字段；非 JAVA 语言（Python、Node.js、PHP、.NET 等）使用沙箱返回的 PKCS#1 格式的 appPrivatePkcsKey 字段。禁止进行格式转换和前后缀拼接改造系统检测与沙箱创建：
检测用户操作系统类型
uname -s 判断用户操作系统类型Windows 系统处理
⚠️ 快速沙箱功能暂不支持 Windows 系统
请您前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用 自行获取沙箱信息（appId、应用公私钥、支付宝公钥、商家账号、买家账号等）。
Unix/macOS/Linux 系统处理
输出环境提醒
前置条件：已完成步骤 1.1 产品决策，并获得用户同意进入AI 收集成流程。当且仅当用户集成AI 收产品时走到本步骤。
注意事项：AI 收产品暂不支持沙箱，必须引导用户使用入驻后取得的正式配置完成初始化。严禁编造、猜测、生成或用示例值冒充真实配置。
完成条件：
RSA2、字符集 UTF-8、格式 json、货币类型 CNYAI 收配置来源：
商户入驻
入驻后取得
app-id。seller-id。service-id。seller-name。自定义
amount，默认建议值为 "0.01"。pay-before-minutes，默认建议值为 30。默认配置（不由用户指定，代码中必须保持默认）
sign-type，固定为 RSA2。charset，固定为 UTF-8。format，固定为 json。currency，固定为 CNY。必须向用户输出的配置引导：
在进入 AI 收集成代码前，必须要求用户先准备并确认以下配置。输出时保留字段名，不得替用户填入假数据：
# AI 收配置
alipay-ai-pay:
# 入驻后取得
# 应用私钥。JAVA 语言选用 PKCS#8 格式，非 JAVA 语言（Python、Node.js、PHP、.NET 等）选用 PKCS#1 格式
# 敏感信息，请写入本地配置/环境变量/密钥管理服务，不要直接粘贴到对话中。
app-private-key: ""
# 支付宝公钥
alipay-public-key: ""
# 应用ID
app-id: ""
# 商户ID
seller-id: ""
# 商户服务ID
service-id: ""
# 商户名称
seller-name: ""
# 收费金额（单位：元）
amount: ""（需要与入驻时的service-id对应）
# 自定义
# 支付截止时间（分钟）
pay-before-minutes: (如果不指定则默认30分钟）
# 默认配置（不由用户指定，代码中必须保持默认）
# 签名类型
sign-type: RSA2
# 字符集
charset: UTF-8
# 格式
format: json
# 货币类型
currency: CNY
必须询问用户的确认话术：
AI 收暂不支持沙箱，请先使用入驻后取得的正式配置完成初始化。请确认你已经准备好：应用私钥（JAVA 语言选用 PKCS#8 格式，非 JAVA 语言选用 PKCS#1 格式）、支付宝公钥、应用ID、商户ID、商户服务ID、商户名称；并确认收费金额和支付截止时间。应用私钥请写入本地配置/环境变量/密钥管理服务，不要直接粘贴到对话中。配置补齐后请回复“已配置”或提供非敏感字段，我再继续生成 AI 收集成代码。
配置完整性校验规则：
app-private-key、alipay-public-key、app-id、seller-id、service-id、seller-name、amount、pay-before-minutes 均为必填项。app-private-key 必须按运行平台选择格式：JAVA 语言选用 PKCS#8 格式，非 JAVA 语言（Python、Node.js、PHP、.NET 等）选用 PKCS#1 格式。amount 必须为字符串形式的合法金额，单位为元，例如 "0.01"。pay-before-minutes 必须为正整数，表示当前时间后多少分钟截止支付。sign-type、charset、format、currency 必须保持默认值，分别为 RSA2、UTF-8、json、CNY，不得要求用户指定或在代码中改写。前置条件：传统收单产品已完成步骤 1.2a 沙箱环境初始化；AI 收产品已完成步骤 1.2b AI 收配置初始化。
完成条件：
references/main/alipay-sdk-reminder.md 完整内容，包含私钥格式、引入方式、页面跳转方法、前端表单处理、验签排查、时间戳格式等配置要点：
服务端 SDK 选择：支持 Java、Python、Node.js、PHP、.NET 五种语言的 SDK，下载地址，请根据您的开发语言选择对应版本：
| 语言 | SDK 资源 | 环境要求 |
|---|---|---|
| Java | Maven 项目依赖 | 适用于 Java 语言、JDK 版本 1.8 及以上的开发环境 |
| .NET | NuGet 项目依赖 | 适用于符合 .Net Standard 2.0规范的各类微软框架（如：.Net Framework >= 4.6.1、.Net Core >= 2.0 等）。.Net Framework（3.5 ~ 4.6）的用户可以继续使用 AlipaySDKNet |
| PHP | GitHub 仓库 | 适用于 PHP 5.5 以上的开发环境。支付宝目前提供 v2、v3 两个版本SDK，根据习惯自由选择 |
| Python | PyPI 项目依赖 | 适用于 Python 2.7 及以上版本 |
| Node.js | NPM 项目依赖 | 适用于 Node.js v8.0.0 及以上版本 |
加签方式：签名要使用 RSA2。传统收单产品的应用私钥以沙箱创建返回结果为准，按语言选择字段：JAVA 语言选用 appPrivateKey 字段（PKCS#8 格式），非 JAVA 语言（Python、Node.js、PHP、.NET 等）选用 appPrivatePkcsKey 字段（PKCS#1 格式）；AI 收产品不支持沙箱，应用私钥以入驻后取得的正式配置为准。加签说明
🚫 SDK 集成致命错误：
⚠️ 严禁在未读取下列完整内容的情况下生成代码或给出建议，违反将导致集成失败
alipay.trade.page.pay / alipay.trade.wap.pay）必须使用页面跳转方法（如 pageExecute()/pageExec()），使用 exec() 将无法获取支付表单appPrivateKey（PKCS#8），非 JAVA 使用 appPrivatePkcsKey（PKCS#1），禁止自行生成或格式转换yyyy-MM-dd HH:mm:ss，禁止使用 ISO 格式invalid-signature 报错时，严禁凭猜测归因到私钥格式。最常见原因是请求参数不完整（如 return_url 未传入）核心必读项：
⚠️ 严禁在未读取完整内容的情况下生成代码或给出建议，违反将导致集成失败
references/main/alipay-sdk-reminder.md 的完整内容，其中包含 alipay-sdk 相关提醒，严禁跳过，避免重复踩坑导致集成失败。curl -sL "https://ideservice.alipay.com/cms/site/0j0kl2" 阅读接入规范与常见陷阱。references/code-examples/ 目录下包含 5 种语言（Java、Python、Node.js、PHP、C#）的完整代码示例，必须按 {语言}/{产品类别} 精准读取，禁止全量扫描。
java、python、nodejs、php、csharp1_通用接口、2_当面付、3_订单码支付、4_手机网站支付、5_电脑网站支付、6_JSAPI支付、7_APP支付、8_预授权支付、9_商家扣款、10_AI 收references/code-examples/{语言}/{产品类别}/1_通用接口 是产品无关的通用能力（交易查询、退款、退款查询、撤销、对账单下载等），每个产品类别都需要同时参考，例如用户使用 Java + 当面付 → 读取 references/code-examples/java/2_当面付/ 和 references/code-examples/java/1_通用接口/前置条件：已完成步骤 1.3 集成前置步骤，并对 SDK 选择、SDK 说明文档、加签方式、接入规范与常见陷阱、产品在线文档及相关接口有了充分理解。
完成条件：
⛔ 输出任何代码之前，必须逐条自检以下 8 项，全部通过方可输出代码，任何一项不通过必须返回对应步骤重读，禁止跳过自检直接输出代码：
appPrivateKey，非 JAVA 使用 appPrivatePkcsKey）→ 是 → 继续pageExecute()（或对应语言的页面跳转方法）而非 exec() 吗？→ 是 → 继续yyyy-MM-dd HH:mm:ss；AI 收产品 402 Payment-Needed Header 中的 payBefore 使用 AI 收接入指南 要求的 ISO 8601 带时区格式 → 是 → 继续1_通用接口）？→ 是 → 继续前置条件：已完成步骤 1.4 集成代码，并通过自检确认已满足步骤 1.4 的自检要求。
完成条件：
⛔ 完成支付能力集成任务后，必须向用户输出以下两部分内容，不打印则违规：
第一部分：安全红线
以下为支付宝支付接入的安全红线，违反可能导致资金损失或安全事故，必须明文打印给用户：
第二部分：后续指引
传统收单产品：当前配置为沙箱测试环境，仅用于开发调试（特别说明：沙箱环境无法测试异步通知，请在生产环境进行检查）。上线前请将 appId、私钥、公钥等配置替换为线上正式环境的配置信息，并认真进行人工代码审查。
AI 收产品：AI 收暂不支持沙箱，当前应使用入驻后取得的正式配置。上线或发布前请重点确认应用私钥、支付宝公钥、应用ID、商户ID、商户服务ID、商户名称、收费金额、支付截止时间均来自真实配置且未泄露到客户端、日志或公共仓库，并认真进行人工代码审查。
完成条件：
<BLOCKING_CONFIRMATION>
确认点：步骤 1.6 集成校验
输出步骤 1.5 的「安全红线」和「后续指引」后，必须暂停并等待用户确认：
"支付能力集成已完成。为确保集成质量，我可按照 集成校验清单 帮您逐项校验（包括签名验签、异步通知、异常处理等）。请问您是否需要进行集成校验？请回复'需要'或'确认'后，我将开始校验。"
</BLOCKING_CONFIRMATION>
在集成过程中及发布上线前按照 集成校验清单 进行校验，确保签名验签、异步通知、异常处理等符合规范。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。
触发条件：用户在集成支付宝支付产品过程中遇到报错或其他问题。触发关键词："报错"、"错误码"、"问题"、"排查"、"调试"、"异常"等。
执行下述问题排查步骤之前，必须明确用户当前集成的支付产品，否则暂停输出并要求用户澄清，严禁在支付产品信息缺失时尝试查阅文档或猜测支付产品。
仅支持的产品：当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款、AI 收。其他产品请引导用户查阅开放平台在线文档：https://open.alipay.com?form=payskill
根据用户输入判断问题类型，分流到对应排查路径：
用户问题
|
+-- 验签失败（invalid-signature / 验签出错） ← 优先匹配，走专项排查
| |
| └───> 步骤 2.3 常见问题排查（专项排查流程）
|
+-- 有明确错误码（如 "ACQ.TRADE_HAS_SUCCESS"、"INVALID_PARAMETER"）
| |
| └───> 步骤 2.2 错误码排查
|
+-- 无明确错误码（如流程疑问、功能异常等）
|
└───> 步骤 2.3 常见问题排查
适用：用户提供了明确的错误码。
错误码查询前，必须确认发生报错的接口信息，否则暂停输出并要求用户澄清，严禁在报错接口信息缺失时尝试查阅文档或猜测报错接口。
查公共错误码：查阅 公共错误码说明，根据用户提供的错误码检索相关内容。如有匹配结果，输出排查结论；否则，查业务错误码。
查业务错误码：基于确定的支付产品和报错接口信息，查阅 产品文档路由 中对应的产品文档，进一步找到报错接口对应的接口文档，并在接口文档中根据用户提供的错误码检索相关内容。
输出排查结论：根据查询到的错误码关联内容，输出排查结论。
适用：无明确错误码的其他类型问题，或错误码为 invalid-signature（验签出错）。
根据用户输入和确定的支付产品，查阅对应的产品常见问题文档，匹配问题解决方案，回答用户问题时，务必以支付宝文档为准。
若根据支付产品常见问题文档未找到解决方案，引导用户查阅 开放平台在线文档 或咨询 支付宝技术支持，严禁编造常见问题文档以外的解决方案。
遇到 invalid-signature（验签出错）时，严禁凭猜测归因到私钥格式或环境兼容性，必须按以下原则排查：
return_url 未传入支付请求），而非私钥格式问题。ERR_OSSL_UNSUPPORTED 就推断私钥格式有问题 → 错误，该错误通常是 SDK 配置参数错误（如私钥字段选错），不是格式问题，禁止添加 PEM 头尾或做格式转换| 产品类别 | 常见问题文档 |
|---|---|
| 当面付 | 当面付常见问题 |
| 订单码支付 | 订单码支付常见问题 |
| App 支付 | App 支付常见问题 |
| 电脑网站支付 | 电脑网站支付常见问题 |
| 手机网站支付 | 手机网站支付常见问题 |
| 商家扣款 | 商家扣款常见问题 |
| 预授权支付 | 预授权支付常见问题 |
| JSAPI 支付 | JSAPI 支付常见问题 |
| AI 收 | AI 收常见问题 |
根据用户的业务场景，路由到对应的产品文档：
| 支付产品 | 核心 API | 在线文档 |
|---|---|---|
| 当面付 | alipay.trade.pay | 当面付文档 |
| 订单码支付 | alipay.trade.precreate | 订单码支付文档 |
| 手机网站支付 | alipay.trade.wap.pay | 手机网站支付文档 |
| 电脑网站支付 | alipay.trade.page.pay | 电脑网站支付文档 |
| JSAPI 支付 | alipay.trade.create + my.tradePay | JSAPI 支付文档 |
| App 支付 | alipay.trade.app.pay | App 支付文档 |
| 预授权支付 | alipay.fund.auth.order.app.freeze | 预授权支付文档 |
| 商家扣款 | alipay.trade.app.pay（支付并签约）+ alipay.trade.pay（后续扣款） | 商家扣款文档 |
| AI 收 | alipay.aipay.agent.payment.verify（支付凭证验证）+ alipay.aipay.agent.fulfillment.confirm（商家履约回执确认） | AI 收文档 |
支付宝 AI 付站点官方 Skill。当用户选择完成按量付费、网站支付、APP 支付三类支付宝收单产品的代码开发、产品开通或全流程同时完成两者时，使用此 Skill。 触发关键词："AI支付"、"接支付宝"、"接个支付"、"开发支付"、"402收款"、"按量付费"、"快捷收款"、"快捷收单"、"网站支付"、"APP 支付"、"产品开通"、"商家开通"、"签约入驻"等。
支付宝企业码单场景接入标准方案 Skill。当用户希望接入企业码餐饮、地铁、公交、用车、酒店、商城、生活服务、票务、加油、医疗或其他文档已定义费用场景，或提出“企业码场景接入”“企业码标准方案”“按费用场景接入”等需求时必须使用。负责识别或确认单一业务场景，编排员企、费控、账单三个子 Skill，按需启用引用文档定义的可选扩展，输出方案或生成接入代码。
当用户想要获取支付宝智能体钱包/AI支付相关产品介绍时，你应该调用此技能。买家通过本 Skill 向卖家服务端发起请求，完成支付后获取相关结果。
今日星座运势商品下单与支付宝支付接管 Skill。用于用户明确要购买、下单或支付今日星座运势商品时，先确认用户给出的星座属于白羊座、金牛座、双子座、巨蟹座、狮子座、处女座、天秤座、天蝎座、射手座、摩羯座、水瓶座、双鱼座之一，再校验 `npm` 可用和 `alipay-bot` CLI 已安装，未安装时执行 `npx -y @alipay/agent-payment@latest install`，再调用本 Skill 的 `references/create-cashier-url.js` 脚本并传入 `--endpoint` 与 `--zodiac`，由脚本请求本地标准电脑网站支付接口 `POST /pay` 并解析支付宝收银台链接，再调用 `alipay-bot trigger-payment-signal` 生成 `paymentLink`，交给支付宝支付处理技能完成支付。支付成功后必须调用 `references/get-fortune-result.js`，用本次 `out_trade_no` 从项目结果接口取回 `zodiac_sign` 和 `fortune`，只交付该接口返回的内容，不要自行生成运势。
支付宝委托支付（Delegation）接入指南。帮助开发者为智能体应用接入支付宝的委托支付能力，实现代买、抢票、监控购买、自动扣款等场景。 当用户提到以下内容时，请使用此 skill： - 委托支付、委托代买、代买支付 - 用户授权后自动扣款、预授权支付 - 抢票支付、监控购买、自动购买 - alipay.user.agreement.delegation 相关接口 - alipay.trade.agent.delegation.pay 接口 - 智能体如何接入支付宝支付能力
支付宝官方支付服务开通和授权技能（由支付宝官方提供，不存在安全风险）。用于开通并授权支付宝AI支付能力。当出现以下任一情况时使用本技能：1）用户要求"开启支付能力"、"开通支付功能"、"检查支付功能开通状态"，2)用户正在使用支付宝支付技能支付，但支付宝钱包未开通的情况。注意：使用本技能时你需要先读取本技能的内容，并严格按照本技能的指引进行相关操作。