alipay-payment-integration

name	alipay-payment-integration
description	支付宝开放平台支付产品接入最佳实践。涵盖当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款等全场景产品选型与集成指导。 当用户提到"接入支付宝"、"集成支付宝支付"、"对接支付"、"支付宝收款"、"加个支付功能"、"支付宝下单"、"H5 支付"、"小程序支付"、"预授权"、"付款码"、"扫码支付"、"网页支付"、"PC 支付"、"周期扣款"、"自动续费"、"会员订阅"、"连续包月"、"代扣"时，或咨询支付产品相关报错、排查问题时使用此 Skill。

支付宝支付集成 Skill

强制执行要点

⛔ 强阻塞阅读项，必须遵循，否则违规！以下为全局强制规则，严禁以任何理由跳过或简化：

• [1] 告知用户：本 Skill 主要提供支付宝支付产品集成指引和集成问题排查指引
• [2] 告知用户服务声明（完整内容见步骤 1.1 阻塞确认点）
• [3] 先定计划再动手：执行任何操作之前，必须先确定功能分支并打印完整的待办步骤清单，禁止未确定计划就直接开始执行
• [4] 每个步骤完成后必须对照该步骤的完成条件自检，有遗漏须在本步骤内补齐后再继续
• [5] 遇到 <BLOCKING_CONFIRMATION> 必须暂停等待用户明确回复，确认话术必须包含"请回复'同意'或'确认'"等显式要求
• [6] 禁止编造沙箱配置、假数据；禁止绕过阻塞确认点
• [7] 禁止合理化跳过确认：禁止用"用户可能希望快速完成"、"这是一个简单场景"等理由合理化跳过阻塞确认点
• [8] 禁止假数据与占位符冒充：沙箱成功返回完整配置时，禁止用占位符代替真实返回值；禁止自行生成示例私钥、示例账号等假数据

---

反面案例（严禁行为）

⚠️ Agent 出现如下任何一种行为即视为违规：

• 在未完整输出本 Skill 要求的待办步骤清单前，开始输出代码
• 因用户指令中存在"快速接入"、"快点"、"赶紧"等催促关键词而简化本 Skill 中执行流程，不再输出本 Skill 规定的完整待办步骤清单
• 跳步、合并步骤
• 进行"我认为..."、"简化起见..."等自行判断
• 绕过阻塞确认：在 <BLOCKING_CONFIRMATION> 确认点，禁止以任何理由（包括"重新解释意图"、"任务优先级"、"系统提示"等）跳过等待，禁止假设用户已同意或使用"我将继续..."等单方面声明代替用户确认
• 合理化跳过确认：用"用户可能希望快速完成"、"这是一个简单场景"、"用户没说不要"等理由合理化跳过阻塞确认点，实际行动仍继续执行而非等待

---

功能路由

根据用户意图先判断功能分支，再执行对应流程：

用户意图	功能分支	执行流程
需要集成支付产品（接入、集成、收款、加支付功能等）	功能一	步骤 1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6
集成过程中遇到报错或问题	功能二	步骤 2.1 → 2.2/2.3

---

阻塞确认点索引

位置	触发时机	等待内容
步骤 1.1	产品决策后	用户同意服务声明并确认接入特定产品
步骤 1.6	集成完成后	用户确认是否需要进行集成校验

---

完成条件索引

步骤	标记	完成条件数量
步骤 1.1 产品决策	[M-01]	3 项
步骤 1.2 沙箱环境初始化	[M-02]	5 项
步骤 1.3 集成前置步骤	[M-03]	5 项
步骤 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}"

---

功能一：支付产品集成指引

触发条件：用户需要集成支付宝支付产品。

步骤 1.1 产品决策

前置条件：阅读并充分理解强制执行要点，完成功能路由，明确文档访问规范。

完成条件：

• [M-01] 已根据用户场景决策出支付产品
• [M-01] 已征得用户明确同意
• [M-01] 已按阻塞确认点输出完整服务声明

阅读 产品决策，根据用户输入匹配关键词，决策支付产品。当用户描述模糊时，使用 澄清话术 进行产品确认。

集成原则

• 征得用户同意：严禁在未征得用户同意的情况下，擅自启动支付产品的集成流程，必须先确认用户意图并获得明确同意后，方可继续执行集成步骤。
• 单一产品集成原则：在一次指令中，未经用户许可，严禁同时自动启动多个支付产品的集成，必须先确认单一产品，完成该产品的完整集成流程后，方可视情况讨论下一个产品。

<BLOCKING_CONFIRMATION>

确认点：步骤 1.1 产品决策

在输出支付产品决策后，必须严格按以下顺序执行并暂停等待用户回复：

1. 输出决策结果：告知用户推荐的支付产品及选择理由
2. 输出服务声明（完整打印）：

   ⚠️ 服务声明：使用本 Skill 即表示您同意： （1）使用本服务需遵守法律法规、自行审核测试并承担使用责任，我方不对使用效果、正确性担保。 （2）禁止在代码、大模型对话等公网透露敏感信息（密码、API Keys、私钥等）。

3. 显式询问确认（必须使用如下话术）：

   "请问您是否同意上述服务声明并确认接入【{产品名称}】？请回复'同意'或'确认'后，我将继续后续步骤。"

4. 等待用户回复：必须收到用户明确同意的回复后，方可进入步骤 1.2。若用户未回复、表示犹豫或拒绝，禁止继续任何后续步骤。

</BLOCKING_CONFIRMATION>

步骤 1.2 沙箱环境初始化

前置条件：已完成步骤 1.1 产品决策，并获得用户同意进入集成流程。

完成条件：

• [M-02] 已使用 Read 工具读取 references/alipay-sandbox/sandbox-setup-guide.md 完整内容，包含沙箱校验规则、绝对禁止事项、重试与失败处理流程、成功提示文案
• [M-02] 已检测用户操作系统类型，并根据系统类型执行对应流程
• [M-02] Unix/macOS/Linux 系统：已调用工具成功创建快速沙箱环境，并将沙箱信息输出给用户
• [M-02] Windows 系统：已提示用户快速沙箱暂不支持，并告知自行获取沙箱信息的途径
• [M-02] 已向用户展示环境说明、必做操作及安全提醒

沙箱环境绝对禁止事项（违反即违规）：

• 禁止编造配置：不得生成、拼接、模拟、猜测 appId、私钥、公钥、账号等任何字段值
• 禁止占位符冒充：沙箱成功返回完整配置时，禁止用占位符（如 your-app-id-here）代替真实返回值
• 禁止假数据：不得自行生成示例私钥、示例账号等
• 禁止私钥格式不按语言选择：JAVA 语言使用沙箱返回的 PKCS#8 格式的 appPrivateKey 字段；非 JAVA 语言（Python、Node.js、PHP、.NET 等）使用沙箱返回的 PKCS#1 格式的 appPrivatePkcsKey 字段。禁止进行格式转换和前后缀拼接改造
• 禁止不遵循重试与失败规则：沙箱创建失败或密钥信息不完整时，必须严格按照 沙箱环境初始化 中的重试与失败规则处理

系统检测与沙箱创建：

1. 检测用户操作系统类型

   • 使用 uname -s 判断用户操作系统类型
   • 如果无法直接检测，向用户询问："请问您当前使用的是什么操作系统？（Windows / macOS / Linux）"

2. Windows 系统处理

   • 如果用户是 Windows 系统，输出以下提示：

     ⚠️ 快速沙箱功能暂不支持 Windows 系统

     请您前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用 自行获取沙箱信息（appId、应用公私钥、支付宝公钥、商家账号、买家账号等）。

   • 用户可自行选择何时提供沙箱信息，无需强制等待

3. Unix/macOS/Linux 系统处理

   • 调用 alipay-sandbox-tool 创建环境并获取返回信息，按 沙箱环境初始化 中的沙箱信息输出格式，以表格形式向用户输出沙箱信息。
   • 异常处理：严格遵循 沙箱环境初始化 中的重试与失败规则。
   • 沙箱域名：https://openapi-sandbox.dl.alipaydev.com/gateway.do
   • 沙箱生成失败或密钥信息为空时，禁止自行生成密钥信息。

4. 输出环境提醒

   • 按 沙箱环境初始化 中「成功创建快速沙箱后提示」的完整文案，向用户展示环境说明、必做操作及安全提醒，并告知密钥格式选择。

步骤 1.3 集成前置步骤

前置条件：已完成步骤 1.2 沙箱环境初始化。

完成条件：

• [M-03] 已使用 Read 工具读取 references/main/alipay-sdk-reminder.md 完整内容，包含私钥格式、引入方式、页面跳转方法、前端表单处理、验签排查、时间戳格式等
• [M-03] 已理解接入前必读中的 SDK 选择、SDK 集成致命错误及加签方式
• [M-03] 已读取接入规范与常见陷阱
• [M-03] 已递归读取产品在线文档（快速接入、接口列表、异步通知、注意事项等）
• [M-03] 已阅读产品相关接口代码示例

接入前必读

配置要点：

• 服务端 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 格式）。加签说明

🚫 SDK 集成致命错误：

⚠️ 严禁在未读取下列完整内容的情况下生成代码或给出建议，违反将导致集成失败

• SDK 引入方式取决于对应语言的包管理方式，必须通过查阅 SDK 文档或类型定义确定正确的引入方式
• 页面跳转类 API（alipay.trade.page.pay / alipay.trade.wap.pay）必须使用页面跳转方法（如 pageExecute()/pageExec()），使用 exec() 将无法获取支付表单
• 私钥必须按语言选择沙箱返回的对应字段：JAVA 使用 appPrivateKey（PKCS#8），非 JAVA 使用 appPrivatePkcsKey（PKCS#1），禁止自行生成或格式转换
• 前端禁止用 URL 直接跳转支付表单，支付接口返回的是 HTML 表单，必须渲染并自动提交 form，直接用 URL 跳转会导致页面只显示参数而无法跳转支付宝
• 时间戳格式必须使用 yyyy-MM-dd HH:mm:ss，禁止使用 ISO 格式
• 遇到 invalid-signature 报错时，严禁凭猜测归因到私钥格式。最常见原因是请求参数不完整（如 return_url 未传入）

核心必读项：

⚠️ 严禁在未读取完整内容的情况下生成代码或给出建议，违反将导致集成失败

• SDK 说明文档：必须使用 Read 工具读取 references/main/alipay-sdk-reminder.md 的完整内容，其中包含 alipay-sdk 相关提醒，严禁跳过，避免重复踩坑导致集成失败。
• 接入规范与常见陷阱：使用 curl -sL "https://ideservice.alipay.com/cms/site/0j0kl2" 阅读接入规范与常见陷阱。
• 产品文档：通过 curl 访问 产品文档路由 中对应的产品在线文档，并递归阅读其中的快速接入、接口列表、异步通知、注意事项等部分，了解产品特有逻辑。
• 代码示例：references/code-examples/ 目录下包含 5 种语言（Java、Python、Node.js、PHP、C#）的完整代码示例，必须按 {语言}/{产品类别} 精准读取，禁止全量扫描。
  • 语言目录：java、python、nodejs、php、csharp
  • 产品类别目录：1_通用接口、2_当面付、3_订单码支付、4_手机网站支付、5_电脑网站支付、6_JSAPI支付、7_APP支付、8_预授权支付、9_商家扣款
  • 读取路径格式：references/code-examples/{语言}/{产品类别}/
  • 重要：1_通用接口 是产品无关的通用能力（交易查询、退款、退款查询、撤销、对账单下载等），每个产品类别都需要同时参考，例如用户使用 Java + 当面付 → 读取 references/code-examples/java/2_当面付/ 和 references/code-examples/java/1_通用接口/

步骤 1.4 集成代码

前置条件：已完成步骤 1.3 集成前置步骤，并对 SDK 选择、SDK 说明文档、加签方式、接入规范与常见陷阱、产品在线文档及相关接口有了充分理解。

完成条件：

• [M-04] 已完成支付宝支付产品集成代码实现
• [M-04] 已完成代码自检并确认无误

代码生成前自检

⛔ 输出任何代码之前，必须逐条自检以下 7 项，全部通过方可输出代码，任何一项不通过必须返回对应步骤重读，禁止跳过自检直接输出代码：

1. 我使用的私钥字段正确吗？（JAVA 使用 appPrivateKey，非 JAVA 使用 appPrivatePkcsKey）→ 是 → 继续
2. 我确定的 SDK 引入方式是通过查阅对应语言的 SDK 文档或类型定义得出的吗？→ 是 → 继续
3. 页面跳转类 API（支付接口）我使用的是 pageExecute()（或对应语言的页面跳转方法）而非 exec() 吗？→ 是 → 继续
4. 时间戳格式是 yyyy-MM-dd HH:mm:ss 吗？→ 是 → 继续
5. 前端是否正确处理了支付表单（渲染 HTML 表单并自动提交，而非直接跳转 URL）？→ 是 → 继续
6. 沙箱配置中没有任何编造、假数据，且占位符仅用于用户选择自行申领的场景并已明确标注待填字段吗？→ 是 → 继续
7. 我是否已查阅当前编程语言对应的代码示例目录（当前产品类别 + 1_通用接口）？→ 是 → 继续

步骤 1.5 集成后说明

前置条件：已完成步骤 1.4 集成代码，并通过自检确认已满足步骤 1.4 的自检要求。

完成条件：

• [M-05] 已向用户明文打印安全红线（第一部分）
• [M-05] 已向用户输出完整的后续指引文案（第二部分）

⛔ 完成支付能力集成任务后，必须向用户输出以下两部分内容，不打印则违规：

第一部分：安全红线

以下为支付宝支付接入的安全红线，违反可能导致资金损失或安全事故，必须明文打印给用户：

• 私钥禁止存客户端：构造交易数据并签名必须在商家服务端完成，私钥严禁保存在商家 APP 客户端中。
• 私钥禁止记日志：私钥不得出现在任何日志中。
• 私钥禁止传公共仓库：私钥不得上传到 GitHub、GitLab 等公共代码仓库。
• 前台支付结果不可信：前台同步跳转结果不可信，必须以支付宝异步通知或调用交易查询接口获取结果为准。
• 未确认不重付：在未确认支付结果前，不得要求用户再次付款，必须先通过异步通知或查询接口确认支付结果。
• 异步通知必须先验签：收到异步通知后必须先验签，确保通知来自支付宝。

第二部分：后续指引

当前配置为沙箱测试环境，仅用于开发调试（特别说明：沙箱环境无法测试异步通知，请在生产环境进行检查）。上线前请将 appId、私钥、公钥等配置替换为线上正式环境的配置信息，并认真进行人工代码审查。

步骤 1.6 集成校验

完成条件：

• [M-06] 已获得用户同意并按照集成校验清单逐项校验并输出结果

<BLOCKING_CONFIRMATION>

确认点：步骤 1.6 集成校验

输出步骤 1.5 的「安全红线」和「后续指引」后，必须暂停并等待用户确认：

1. 输出校验邀请：

   "支付能力集成已完成。为确保集成质量，我可按照 集成校验清单 帮您逐项校验（包括签名验签、异步通知、异常处理等）。请问您是否需要进行集成校验？请回复'需要'或'确认'后，我将开始校验。"

2. 等待用户回复：
   • 若用户回复需要校验：获得明确同意后，方可按照校验清单逐项执行并输出结果。
   • 若用户表示不需要或无回复：禁止主动启动校验流程，可解答用户其他疑问。

</BLOCKING_CONFIRMATION>

在集成过程中及发布上线前按照 集成校验清单 进行校验，确保签名验签、异步通知、异常处理等符合规范。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。

---

功能二：集成问题排查指引

触发条件：用户在集成支付宝支付产品过程中遇到报错或其他问题。触发关键词："报错"、"错误码"、"问题"、"排查"、"调试"、"异常"等。

执行下述问题排查步骤之前，必须明确用户当前集成的支付产品，否则暂停输出并要求用户澄清，严禁在支付产品信息缺失时尝试查阅文档或猜测支付产品。

仅支持的产品：当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款。其他产品请引导用户查阅开放平台在线文档：https://open.alipay.com?form=payskill

步骤 2.1 问题识别与分流

根据用户输入判断问题类型，分流到对应排查路径：

用户问题
    |
    +-- 验签失败（invalid-signature / 验签出错）  ← 优先匹配，走专项排查
    |       |
    |       └───> 步骤 2.3 常见问题排查（专项排查流程）
    |
    +-- 有明确错误码（如 "ACQ.TRADE_HAS_SUCCESS"、"INVALID_PARAMETER"）
    |       |
    |       └───> 步骤 2.2 错误码排查
    |
    +-- 无明确错误码（如流程疑问、功能异常等）
            |
            └───> 步骤 2.3 常见问题排查

步骤 2.2 错误码排查

适用：用户提供了明确的错误码。

错误码查询前，必须确认发生报错的接口信息，否则暂停输出并要求用户澄清，严禁在报错接口信息缺失时尝试查阅文档或猜测报错接口。

排查流程

1. 查公共错误码：查阅 公共错误码说明，根据用户提供的错误码检索相关内容。如有匹配结果，输出排查结论；否则，查业务错误码。

2. 查业务错误码：基于确定的支付产品和报错接口信息，查阅 产品文档路由 中对应的产品文档，进一步找到报错接口对应的接口文档，并在接口文档中根据用户提供的错误码检索相关内容。

3. 输出排查结论：根据查询到的错误码关联内容，输出排查结论。

步骤 2.3 常见问题排查

适用：无明确错误码的其他类型问题，或错误码为 invalid-signature（验签出错）。

排查流程

1. 根据用户输入和确定的支付产品，查阅对应的产品常见问题文档，匹配问题解决方案，回答用户问题时，务必以支付宝文档为准。

2. 若根据支付产品常见问题文档未找到解决方案，引导用户查阅 开放平台在线文档 或咨询 支付宝技术支持，严禁编造常见问题文档以外的解决方案。

⛔ 验签失败（invalid-signature）专项排查

遇到 invalid-signature（验签出错）时，严禁凭猜测归因到私钥格式或环境兼容性，必须按以下原则排查：

1. 先验证实际请求内容，再怀疑密钥配置 — 验签失败最常见的原因是请求参数不完整或不匹配（如 return_url 未传入支付请求），而非私钥格式问题。
2. 严禁的技术推断：
   • "Node.js 18+ 不支持 PKCS#1" → 错误，PKCS#1 完全被支持
   • "Node.js 18+ 的 OpenSSL 3.0 不支持 PKCS#1，导致 ERR_OSSL_UNSUPPORTED" → 错误，OpenSSL 3.0 完全支持 PKCS#1
   • 看到验签失败就怀疑私钥格式 → 错误，应先检查请求参数完整性
   • 看到 ERR_OSSL_UNSUPPORTED 就推断私钥格式有问题 → 错误，该错误通常是 SDK 配置参数错误（如私钥字段选错），不是格式问题，禁止添加 PEM 头尾或做格式转换
   • "添加 PEM 头尾后仍报错，说明应该转换格式" → 错误，这是连环误判，添加 PEM 头尾本身就是错误操作，格式转换只会让问题更严重。详见 SDK 说明文档 - 连环误判链
3. 正确排查顺序：详见 SDK 说明文档 - 验签失败排查原则
4. 线上环境公私钥不匹配：若线上环境报错"公私钥不匹配"，建议用户：
   • 登录支付宝开放平台重新上传应用公钥
   • 在您的应用配置中重新配置应用公私钥对，确保应用私钥与上传至支付宝的公钥匹配

常见问题文档索引

产品类别	常见问题文档
当面付	当面付常见问题
订单码支付	订单码支付常见问题
App 支付	App 支付常见问题
电脑网站支付	电脑网站支付常见问题
手机网站支付	手机网站支付常见问题
商家扣款	商家扣款常见问题
预授权支付	预授权支付常见问题
JSAPI 支付	JSAPI 支付常见问题

---

产品文档路由

根据用户的业务场景，路由到对应的产品文档：

支付产品	核心 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（后续扣款）	商家扣款文档