alipay-payment-integration

# 支付宝支付集成 Skill ## 强制执行要点 ⛔ 强阻塞阅读项，必须遵循，否则违规！以下为全局强制规则，**严禁**以任何理由跳过或简化： - [1] 告知用户：本 Skill 主要提供支付宝支付产品集成指引和集成问题排查指引 - [2] 告知用户服务声明（完整内容见步骤 1.1 阻塞确认点） - [3] **先定计划再动手**：执行任何操作之前，**必须先确定功能分支并打印完整的待办步骤清单**，禁止未确定计划就直接开始执行 - [4] 每个步骤完成后必须对照该步骤的**完成条件**自检，有遗漏须在本步骤内补齐后再继续 - [5] 遇到 `<BLOCKING_CONFIRMATION>` 必须暂停等待用户明确回复，确认话术必须包含"请回复'同意'或'确认'"等显式要求 - [6] 禁止编造沙箱配置、假数据；禁止绕过阻塞确认点 - [7] **禁止合理化跳过确认**：禁止用"用户可能希望快速完成"、"这是一个简单场景"等理由合理化跳过阻塞确认点 - [8] **禁止假数据与占位符冒充**：沙箱成功返回完整配置时，禁止用占位符代替真实返回值；禁止自行生成示例私钥、示例账号等假数据 --- ## 反面案例（严禁行为） ⚠️ Agent 出现如下任何一种行为即视为违规： - 在未完整输出本 Skill 要求的**待办步骤清单**前，开始输出代码 - 因用户指令中存在"快速接入"、"快点"、"赶紧"等催促关键词而简化本 Skill 中执行流程，不再输出本 Skill 规定的完整待办步骤清单 - 跳步、合并步骤 - 进行"我认为..."、"简化起见..."等自行判断 - **绕过阻塞确认**：在 `<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 获取支付宝在线文档，文档内链接（产品介绍、接入准备、接口文档等）需递归访问获取完整内容： ```bash curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}" ``` --- ## 功能一：支付产品集成指引 **触发条件**：用户需要集成支付宝支付产品。 ### 步骤 1.1 产品决策 **前置条件**：阅读并充分理解**强制执行要点**，完成**功能路由**，明确**文档访问规范**。 **完成条件**： - [M-01] 已根据用户场景决策出支付产品 - [M-01] 已征得用户明确同意 - [M-01] 已按阻塞确认点输出完整服务声明 阅读 [产品决策](references/main/product-decision.md)，根据用户输入匹配关键词，决策支付产品。当用户描述模糊时，使用 [澄清话术](references/main/product-decision.md) 进行产品确认。 #### 集成原则 - **征得用户同意**：**严禁**在未征得用户同意的情况下，擅自启动支付产品的集成流程，必须先确认用户意图并获得明确同意后，方可继续执行集成步骤。 - **单一产品集成原则**：在一次指令中，未经用户许可，**严禁**同时自动启动多个支付产品的集成，必须先确认单一产品，完成该产品的完整集成流程后，方可视情况讨论下一个产品。 <BLOCKING_CONFIRMATION> **确认点：步骤 1.1 产品决策** 在输出支付产品决策后，**必须严格按以下顺序执行并暂停等待用户回复**： 1. **输出决策结果**：告知用户推荐的支付产品及选择理由 2. **输出服务声明**（完整打印）： > ⚠️ **服务声明**：使用本 Skill 即表示您同意： > （1）使用本服务需遵守法律法规、自行审核测试并承担使用责任，我方不对使用效果、正确性担保。 > （2）禁止在代码、大模型对话等公网透露敏感信息（密码、API Keys、私钥等）。 3. **显式询问确认**（必须使用如下话术）： > "请问您是否同意上述服务声明并确认接入【{产品名称}】？**请回复'同意'或'确认'后**，我将继续后续步骤。" 4. **等待用户回复**：必须收到用户明确同意的回复后，方可进入步骤 1.2。若用户未回复、表示犹豫或拒绝，**禁止**继续任何后续步骤。 </BLOCKING_CONFIRMATION> ### 步骤 1.2a 传统收单产品沙箱环境初始化 **注意事项**：AI 收产品暂不支持沙箱，跳过该步骤，进入1.2b。 **前置条件**：已完成步骤 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` 字段。**禁止进行格式转换和前后缀拼接改造** - **禁止不遵循重试与失败规则**：沙箱创建失败或密钥信息不完整时，必须严格按照 [沙箱环境初始化](references/alipay-sandbox/sandbox-setup-guide.md) 中的重试与失败规则处理 **系统检测与沙箱创建**： 1. **检测用户操作系统类型** - 使用 `uname -s` 判断用户操作系统类型 - 如果无法直接检测，向用户询问："请问您当前使用的是什么操作系统？（Windows / macOS / Linux）" 2. **Windows 系统处理** - 如果用户是 Windows 系统，输出以下提示： > ⚠️ **快速沙箱功能暂不支持 Windows 系统** > > 请您前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用 自行获取沙箱信息（appId、应用公私钥、支付宝公钥、商家账号、买家账号等）。 - 用户可自行选择何时提供沙箱信息，无需强制等待 3. **Unix/macOS/Linux 系统处理** - 调用 [alipay-sandbox-tool](references/alipay-sandbox/alipay-sandbox-tool.md) 创建环境并获取返回信息，按 [沙箱环境初始化](references/alipay-sandbox/sandbox-setup-guide.md) 中的沙箱信息输出格式，以表格形式向用户输出沙箱信息。 - 异常处理：**严格**遵循 [沙箱环境初始化](references/alipay-sandbox/sandbox-setup-guide.md) 中的重试与失败规则。 - 沙箱域名：https://openapi-sandbox.dl.alipaydev.com/gateway.do - 沙箱生成失败或密钥信息为空时，禁止自行生成密钥信息。 4. **输出环境提醒** - 按 [沙箱环境初始化](references/alipay-sandbox/sandbox-setup-guide.md) 中「成功创建快速沙箱后提示」的完整文案，向用户展示环境说明、必做操作及安全提醒，并告知密钥格式选择。 ### 步骤 1.2b AI 收配置初始化 **前置条件**：已完成步骤 1.1 产品决策，**并获得用户同意进入AI 收集成流程**。当且仅当用户集成AI 收产品时走到本步骤。 **注意事项**：AI 收产品暂不支持沙箱，必须引导用户使用入驻后取得的正式配置完成初始化。严禁编造、猜测、生成或用示例值冒充真实配置。 **完成条件**： - [M-02b] 已明确告知用户 AI 收暂不支持沙箱，需要使用入驻后取得的正式配置 - [M-02b] 已引导用户完成商户入驻：智能收产品需先在[商户一站式入驻平台](https://b.alipay.com/page/home/open-ai-pay)上架产品，再接入功能 - [M-02b] 已要求用户提供「入驻后取得」配置：应用私钥（JAVA 语言选用 PKCS#8 格式，非 JAVA 语言选用 PKCS#1 格式）、支付宝公钥、应用ID、商户ID、商户服务ID、商户名称 - [M-02b] 已要求用户确认或提供「自定义」配置：收费金额（单位：元）、支付截止时间（分钟） - [M-02b] 已明确告知「默认配置」不由用户指定，代码中必须保持默认值：签名类型 `RSA2`、字符集 `UTF-8`、格式 `json`、货币类型 `CNY` - [M-02b] 已提醒用户不要在大模型对话或公网环境中直接粘贴应用私钥，建议写入本地配置文件、环境变量或密钥管理服务 - [M-02b] 已对配置完整性做自检：缺少必填项时暂停并要求用户补齐，禁止继续生成集成代码 **AI 收配置来源**： 1. **商户入驻** - **智能收产品开通上架**：先在[商户一站式入驻平台](https://b.alipay.com/page/home/open-ai-pay)上架产品，再接入功能。 2. **入驻后取得** - **应用私钥**：用于生成 AI 收协议中的商家签名和服务端调用签名。JAVA 语言选用 PKCS#8 格式，非 JAVA 语言（Python、Node.js、PHP、.NET 等）选用 PKCS#1 格式。该字段属于敏感信息，必须提醒用户不要直接粘贴到对话中。 - **支付宝公钥**：用于支付宝响应或通知验签。 - **应用ID**：配置键为 `app-id`。 - **商户ID**：配置键为 `seller-id`。 - **商户服务ID**：配置键为 `service-id`。 - **商户名称**：配置键为 `seller-name`。 3. **自定义** - **收费金额（单位：元）**：配置键为 `amount`，默认建议值为 `"0.01"`。 - **支付截止时间（分钟）**：配置键为 `pay-before-minutes`，默认建议值为 `30`。 4. **默认配置（不由用户指定，代码中必须保持默认）** - **签名类型**：配置键为 `sign-type`，固定为 `RSA2`。 - **字符集**：配置键为 `charset`，固定为 `UTF-8`。 - **格式**：配置键为 `format`，固定为 `json`。 - **货币类型**：配置键为 `currency`，固定为 `CNY`。 **必须向用户输出的配置引导**： 在进入 AI 收集成代码前，必须要求用户先准备并确认以下配置。输出时保留字段名，不得替用户填入假数据： ```yaml # 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.3 或生成代码。 ### 步骤 1.3 集成前置步骤 **前置条件**：传统收单产品已完成步骤 1.2a 沙箱环境初始化；AI 收产品已完成步骤 1.2b AI 收配置初始化。 **完成条件**： - [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，[下载地址](https://ideservice.alipay.com/cms/site/0j0cjj)，请根据您的开发语言选择对应版本： | 语言 | SDK 资源 | 环境要求 | | --- | --- | --- | | Java | [Maven 项目依赖](https://central.sonatype.com/artifact/com.alipay.sdk/alipay-sdk-java?smo=true) | 适用于 Java 语言、JDK 版本 1.8 及以上的开发环境 | | .NET | [NuGet 项目依赖](https://www.nuget.org/packages/AlipaySDKNet.Standard/) | 适用于符合 .Net Standard 2.0规范的各类微软框架（如：.Net Framework >= 4.6.1、.Net Core >= 2.0 等）。.Net Framework（3.5 ~ 4.6）的用户可以继续使用 [AlipaySDKNet](https://www.nuget.org/packages/AlipaySDKNet/) | | PHP | [GitHub 仓库](https://github.com/alipay/alipay-sdk-php-all/tree/master) | 适用于 PHP 5.5 以上的开发环境。支付宝目前提供 v2、v3 两个版本SDK，根据习惯自由选择 | | Python | [PyPI 项目依赖](https://pypi.org/project/alipay-sdk-python/) | 适用于 Python 2.7 及以上版本 | | Node.js | [NPM 项目依赖](https://www.npmjs.com/package/alipay-sdk) | 适用于 Node.js v8.0.0 及以上版本 | - **加签方式**：签名要使用 RSA2。传统收单产品的应用私钥以沙箱创建返回结果为准，按语言选择字段：JAVA 语言选用 `appPrivateKey` 字段（PKCS#8 格式），非 JAVA 语言（Python、Node.js、PHP、.NET 等）选用 `appPrivatePkcsKey` 字段（PKCS#1 格式）；AI 收产品不支持沙箱，应用私钥以入驻后取得的正式配置为准。[加签说明](https://ideservice.alipay.com/cms/site/0j3u72) **🚫 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_商家扣款`、`10_AI 收` - **读取路径格式**：`references/code-examples/{语言}/{产品类别}/` - **重要**：`1_通用接口` 是产品无关的通用能力（交易查询、退款、退款查询、撤销、对账单下载等），**每个产品类别都需要同时参考**，例如用户使用 Java + 当面付 → 读取 `references/code-examples/java/2_当面付/` **和** `references/code-examples/java/1_通用接口/` - **AI 收产品**：AI 收产品的示例代码包含接口调用外的功能实现逻辑，在实现AI 收功能时，必须不重不漏地实现。 ### 步骤 1.4 集成代码 **前置条件**：已完成步骤 1.3 集成前置步骤，并对 SDK 选择、SDK 说明文档、加签方式、接入规范与常见陷阱、产品在线文档及相关接口有了充分理解。 **完成条件**： - [M-04] 已完成支付宝支付产品集成代码实现 - [M-04] 已完成代码自检并确认无误 #### 代码生成前自检 **⛔ 输出任何代码之前，必须逐条自检以下 8 项**，全部通过方可输出代码，任何一项不通过必须返回对应步骤重读，**禁止**跳过自检直接输出代码： 1. 我使用的私钥字段正确吗？（JAVA 使用 `appPrivateKey`，非 JAVA 使用 `appPrivatePkcsKey`）→ 是 → 继续 2. 我确定的 SDK 引入方式是通过查阅对应语言的 SDK 文档或类型定义得出的吗？→ 是 → 继续 3. 页面跳转类 API（支付接口）我使用的是 `pageExecute()`（或对应语言的页面跳转方法）而非 `exec()` 吗？→ 是 → 继续 4. 时间戳格式是否符合当前产品要求？传统支付接口使用 `yyyy-MM-dd HH:mm:ss`；AI 收产品 402 `Payment-Needed` Header 中的 `payBefore` 使用 [AI 收接入指南](https://ideservice.alipay.com/cms/site/0j7svz) 要求的 ISO 8601 带时区格式 → 是 → 继续 5. 前端是否正确处理了支付表单（渲染 HTML 表单并自动提交，而非直接跳转 URL）？→ 是 → 继续 6. 配置信息是否没有任何编造、假数据？传统收单产品需检查沙箱配置真实完整；AI 收产品需检查入驻后正式配置真实完整；占位符仅用于用户选择自行申领/自行配置的场景并已明确标注待填字段 → 是 → 继续 7. 我是否已查阅当前编程语言对应的代码示例目录（当前产品类别 + `1_通用接口`）？→ 是 → 继续