Skip to content

xinetzone/SpecWeave / .agents/skills/alipay-payment-integration

alipay-payment-integration

Flagged

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

FileKindSize
SKILL.mdskill md24.8 KB
references/alipay-sandbox/EXAMPLES.mdmarkdown1.3 KB
references/alipay-sandbox/alipay-sandbox-tool.mdmarkdown2.2 KB
references/alipay-sandbox/sandbox-setup-guide.mdmarkdown9.5 KB
references/code-examples/csharp/1_通用接口/收单退款冲退完成通知接口代码示例.mdmarkdown1.2 KB
references/code-examples/csharp/1_通用接口/查询对账单下载地址接口代码示例.mdmarkdown3.0 KB
references/code-examples/csharp/1_通用接口/统一收单交易撤销接口代码示例.mdmarkdown2.7 KB
references/code-examples/csharp/1_通用接口/统一收单交易查询接口代码示例.mdmarkdown7.1 KB
references/code-examples/csharp/1_通用接口/统一收单交易退款接口代码示例.mdmarkdown6.8 KB
references/code-examples/csharp/1_通用接口/统一收单交易退款查询接口代码示例.mdmarkdown5.9 KB
references/code-examples/csharp/2_当面付/统一收单交易支付接口代码示例.mdmarkdown6.5 KB
references/code-examples/csharp/3_订单码支付/统一收单线下交易预创建接口代码示例.mdmarkdown4.7 KB
references/code-examples/csharp/4_手机网站支付/手机网站支付接口代码示例.mdmarkdown6.8 KB
references/code-examples/csharp/5_电脑网站支付/统一收单下单并支付页面接口代码示例.mdmarkdown7.9 KB
references/code-examples/csharp/6_JSAPI支付/统一收单交易创建接口代码示例.mdmarkdown3.8 KB
references/code-examples/csharp/7_APP支付/APP支付接口代码示例.mdmarkdown5.8 KB
references/code-examples/csharp/8_预授权支付/线上资金授权冻结接口代码示例.mdmarkdown6.2 KB
references/code-examples/csharp/8_预授权支付/统一收单交易支付接口(预授权转支付)代码示例.mdmarkdown6.0 KB
references/code-examples/csharp/8_预授权支付/资金授权冻结接口代码示例.mdmarkdown5.4 KB
references/code-examples/csharp/8_预授权支付/资金授权发码接口代码示例.mdmarkdown5.2 KB
references/code-examples/csharp/8_预授权支付/资金授权撤销接口代码示例.mdmarkdown3.4 KB
references/code-examples/csharp/8_预授权支付/资金授权操作查询接口代码示例.mdmarkdown4.4 KB
references/code-examples/csharp/8_预授权支付/资金授权解冻接口代码示例.mdmarkdown3.3 KB
references/code-examples/csharp/9_商家扣款/APP支付接口(支付并签约)代码示例.mdmarkdown4.7 KB
references/code-examples/csharp/9_商家扣款/支付宝个人代扣协议查询接口代码示例.mdmarkdown4.8 KB
references/code-examples/csharp/9_商家扣款/支付宝个人代扣协议解约接口代码示例.mdmarkdown3.9 KB
references/code-examples/csharp/9_商家扣款/统一收单交易支付接口(商家扣款)代码示例.mdmarkdown6.4 KB
references/code-examples/interface-guide.mdmarkdown12.5 KB
references/code-examples/java/1_通用接口/收单退款冲退完成通知接口代码示例.mdmarkdown1.3 KB
references/code-examples/java/1_通用接口/查询对账单下载地址接口代码示例.mdmarkdown3.4 KB
references/code-examples/java/1_通用接口/统一收单交易撤销接口代码示例.mdmarkdown3.0 KB
references/code-examples/java/1_通用接口/统一收单交易查询接口代码示例.mdmarkdown7.4 KB
references/code-examples/java/1_通用接口/统一收单交易退款接口代码示例.mdmarkdown7.2 KB
references/code-examples/java/1_通用接口/统一收单交易退款查询接口代码示例.mdmarkdown6.3 KB
references/code-examples/java/2_当面付/统一收单交易支付接口代码示例.mdmarkdown6.9 KB
references/code-examples/java/3_订单码支付/统一收单线下交易预创建接口代码示例.mdmarkdown5.0 KB
references/code-examples/java/4_手机网站支付/手机网站支付接口代码示例.mdmarkdown7.1 KB
references/code-examples/java/5_电脑网站支付/统一收单下单并支付页面接口代码示例.mdmarkdown8.2 KB
references/code-examples/java/6_JSAPI支付/统一收单交易创建接口代码示例.mdmarkdown4.2 KB
references/code-examples/java/7_APP支付/APP支付接口代码示例.mdmarkdown6.1 KB
references/code-examples/java/8_预授权支付/线上资金授权冻结接口代码示例.mdmarkdown6.5 KB
references/code-examples/java/8_预授权支付/统一收单交易支付接口(预授权转支付)代码示例.mdmarkdown6.5 KB
references/code-examples/java/8_预授权支付/资金授权冻结接口代码示例.mdmarkdown5.9 KB
references/code-examples/java/8_预授权支付/资金授权发码接口代码示例.mdmarkdown5.6 KB
references/code-examples/java/8_预授权支付/资金授权撤销接口代码示例.mdmarkdown3.8 KB
references/code-examples/java/8_预授权支付/资金授权操作查询接口代码示例.mdmarkdown4.8 KB
references/code-examples/java/8_预授权支付/资金授权解冻接口代码示例.mdmarkdown3.8 KB
references/code-examples/java/9_商家扣款/APP支付接口(支付并签约)代码示例.mdmarkdown5.1 KB
references/code-examples/java/9_商家扣款/支付宝个人代扣协议查询接口代码示例.mdmarkdown5.1 KB
references/code-examples/java/9_商家扣款/支付宝个人代扣协议解约接口代码示例.mdmarkdown4.2 KB
references/code-examples/java/9_商家扣款/统一收单交易支付接口(商家扣款)代码示例.mdmarkdown6.9 KB
references/code-examples/nodejs/1_通用接口/收单退款冲退完成通知接口代码示例.mdmarkdown1.1 KB
references/code-examples/nodejs/1_通用接口/查询对账单下载地址接口代码示例.mdmarkdown1.6 KB
references/code-examples/nodejs/1_通用接口/统一收单交易撤销接口代码示例.mdmarkdown1.5 KB
references/code-examples/nodejs/1_通用接口/统一收单交易查询接口代码示例.mdmarkdown5.6 KB
references/code-examples/nodejs/1_通用接口/统一收单交易退款接口代码示例.mdmarkdown4.1 KB
references/code-examples/nodejs/1_通用接口/统一收单交易退款查询接口代码示例.mdmarkdown4.4 KB
references/code-examples/nodejs/2_当面付/统一收单交易支付接口代码示例.mdmarkdown3.5 KB
references/code-examples/nodejs/3_订单码支付/统一收单线下交易预创建接口代码示例.mdmarkdown2.6 KB
references/code-examples/nodejs/4_手机网站支付/手机网站支付接口代码示例.mdmarkdown3.7 KB
references/code-examples/nodejs/5_电脑网站支付/统一收单下单并支付页面接口代码示例.mdmarkdown4.2 KB
references/code-examples/nodejs/7_APP支付/APP支付接口代码示例.mdmarkdown2.9 KB
references/code-examples/nodejs/8_预授权支付/统一收单交易支付接口(预授权转支付)代码示例.mdmarkdown3.5 KB
references/code-examples/nodejs/9_商家扣款/APP支付接口(支付并签约)代码示例.mdmarkdown2.4 KB
references/code-examples/nodejs/9_商家扣款/统一收单交易支付接口(商家扣款)代码示例.mdmarkdown3.6 KB
references/code-examples/php/1_通用接口/收单退款冲退完成通知接口代码示例.mdmarkdown664 B
references/code-examples/php/1_通用接口/查询对账单下载地址接口代码示例.mdmarkdown2.5 KB
references/code-examples/php/1_通用接口/统一收单交易撤销接口代码示例.mdmarkdown2.3 KB
references/code-examples/php/1_通用接口/统一收单交易查询接口代码示例.mdmarkdown6.6 KB
references/code-examples/php/1_通用接口/统一收单交易退款接口代码示例.mdmarkdown5.8 KB
references/code-examples/php/1_通用接口/统一收单交易退款查询接口代码示例.mdmarkdown5.4 KB
references/code-examples/php/2_当面付/统一收单交易支付接口代码示例.mdmarkdown5.4 KB
references/code-examples/php/3_订单码支付/统一收单线下交易预创建接口代码示例.mdmarkdown3.7 KB
references/code-examples/php/4_手机网站支付/手机网站支付接口代码示例.mdmarkdown5.4 KB
references/code-examples/php/5_电脑网站支付/统一收单下单并支付页面接口代码示例.mdmarkdown6.2 KB
references/code-examples/php/6_JSAPI支付/统一收单交易创建接口代码示例.mdmarkdown3.1 KB
references/code-examples/php/7_APP支付/APP支付接口代码示例.mdmarkdown4.5 KB
references/code-examples/php/8_预授权支付/线上资金授权冻结接口代码示例.mdmarkdown5.0 KB
references/code-examples/php/8_预授权支付/统一收单交易支付接口(预授权转支付)代码示例.mdmarkdown5.2 KB
references/code-examples/php/8_预授权支付/资金授权冻结接口代码示例.mdmarkdown4.6 KB
references/code-examples/php/8_预授权支付/资金授权发码接口代码示例.mdmarkdown4.3 KB
references/code-examples/php/8_预授权支付/资金授权撤销接口代码示例.mdmarkdown2.9 KB
references/code-examples/php/8_预授权支付/资金授权操作查询接口代码示例.mdmarkdown3.8 KB
references/code-examples/php/8_预授权支付/资金授权解冻接口代码示例.mdmarkdown2.9 KB
references/code-examples/php/9_商家扣款/APP支付接口(支付并签约)代码示例.mdmarkdown3.6 KB
references/code-examples/php/9_商家扣款/支付宝个人代扣协议查询接口代码示例.mdmarkdown4.2 KB
references/code-examples/php/9_商家扣款/支付宝个人代扣协议解约接口代码示例.mdmarkdown3.2 KB
references/code-examples/php/9_商家扣款/统一收单交易支付接口(商家扣款)代码示例.mdmarkdown5.4 KB
references/code-examples/python/1_通用接口/收单退款冲退完成通知接口代码示例.mdmarkdown1.3 KB
references/code-examples/python/1_通用接口/查询对账单下载地址接口代码示例.mdmarkdown2.4 KB
references/code-examples/python/1_通用接口/统一收单交易撤销接口代码示例.mdmarkdown2.2 KB
references/code-examples/python/1_通用接口/统一收单交易查询接口代码示例.mdmarkdown6.3 KB
references/code-examples/python/1_通用接口/统一收单交易退款接口代码示例.mdmarkdown5.2 KB
references/code-examples/python/1_通用接口/统一收单交易退款查询接口代码示例.mdmarkdown5.2 KB
references/code-examples/python/2_当面付/统一收单交易支付接口代码示例.mdmarkdown3.6 KB
references/code-examples/python/3_订单码支付/统一收单线下交易预创建接口代码示例.mdmarkdown2.1 KB
references/code-examples/python/4_手机网站支付/手机网站支付接口代码示例.mdmarkdown3.0 KB
references/code-examples/python/5_电脑网站支付/统一收单下单并支付页面接口代码示例.mdmarkdown3.2 KB
references/code-examples/python/7_APP支付/APP支付接口代码示例.mdmarkdown2.4 KB
references/main/alipay-sdk-reminder.mdmarkdown11.5 KB
references/main/checklist.mdmarkdown5.5 KB
references/main/product-decision.mdmarkdown4.9 KB
---
source: "镜像自 Trae IDE builtin(源镜像已清理,原镜像标识 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 获取支付宝在线文档,文档内链接(产品介绍、接入准备、接口文档等)需递归访问获取完整内容:

```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.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` 字段。**禁止进行格式转换和前后缀拼接改造**
- **禁止不遵循重试与失败规则**:沙箱创建失败或密钥信息不完整时,必须严格按照 [沙箱环境初始化](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.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,[下载地址](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 格式)。[加签说明](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_商家扣款`
  - **读取路径格式**:`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. **输出校验邀请**:
   > "支付能力集成已完成。为确保集成质量,我可按照 [集成校验清单](references/main/checklist.md) 帮您逐项校验(包括签名验签、异步通知、异常处理等)。**请问您是否需要进行集成校验?请回复'需要'或'确认'后**,我将开始校验。"
2. **等待用户回复**:
   - 若用户回复需要校验:**获得明确同意后**,方可按照校验清单逐项执行并输出结果。
   - 若用户表示不需要或无回复:**禁止**主动启动校验流程,可解答用户其他疑问。

</BLOCKING_CONFIRMATION>

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

---

## 功能二:集成问题排查指引

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

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

**仅支持的产品**:当面付、订单码支付、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. **查公共错误码**:查阅 [公共错误码说明](https://ideservice.alipay.com/cms/site/02km9f),根据用户提供的错误码检索相关内容。如有匹配结果,**输出排查结论**;否则,**查业务错误码**。

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

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

### 步骤 2.3 常见问题排查

**适用**:无明确错误码的其他类型问题,或错误码为 `invalid-signature`(验签出错)。

#### 排查流程

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

2. 若根据支付产品**常见问题文档**未找到解决方案,引导用户查阅 [开放平台在线文档](https://open.alipay.com?form=payskill) 或咨询 [支付宝技术支持](https://opensupport.alipay.com/support/intelligent-services?form=payskill),**严禁**编造常见问题文档以外的解决方案。

#### ⛔ 验签失败(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 说明文档 - 连环误判链](references/main/alipay-sdk-reminder.md)
3. **正确排查顺序**:详见 [SDK 说明文档 - 验签失败排查原则](references/main/alipay-sdk-reminder.md)
4. **线上环境公私钥不匹配**:若线上环境报错"公私钥不匹配",建议用户:
   - 登录支付宝开放平台**重新上传应用公钥**
   - 在您的应用配置中重新配置应用公私钥对,确保应用私钥与上传至支付宝的公钥匹配

#### 常见问题文档索引

| 产品类别 | 常见问题文档 |
| --- | --- |
| 当面付 | [当面付常见问题](https://ideservice.alipay.com/cms/site/0j3j50) |
| 订单码支付 | [订单码支付常见问题](https://ideservice.alipay.com/cms/site/0j3mpk) |
| App 支付 | [App 支付常见问题](https://ideservice.alipay.com/cms/site/0j3pih) |
| 电脑网站支付 | [电脑网站支付常见问题](https://ideservice.alipay.com/cms/site/0j3kh1) |
| 手机网站支付 | [手机网站支付常见问题](https://ideservice.alipay.com/cms/site/0j3pig) |
| 商家扣款 | [商家扣款常见问题](https://ideservice.alipay.com/cms/site/0j3j51) |
| 预授权支付 | [预授权支付常见问题](https://ideservice.alipay.com/cms/site/0j3qcq) |
| JSAPI 支付 | [JSAPI 支付常见问题](https://ideservice.alipay.com/cms/site/0j3pii) |

---

## 产品文档路由

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

| 支付产品 | 核心 API | 在线文档 |
| --- | --- | --- |
| 当面付 | `alipay.trade.pay` | [当面付文档](https://ideservice.alipay.com/cms/site/0izcu3) |
| 订单码支付 | `alipay.trade.precreate` | [订单码支付文档](https://ideservice.alipay.com/cms/site/0izg0z) |
| 手机网站支付 | `alipay.trade.wap.pay` | [手机网站支付文档](https://ideservice.alipay.com/cms/site/0izne3) |
| 电脑网站支付 | `alipay.trade.page.pay` | [电脑网站支付文档](https://ideservice.alipay.com/cms/site/0iztfv) |
| JSAPI 支付 | `alipay.trade.create` + `my.tradePay` | [JSAPI 支付文档](https://ideservice.alipay.com/cms/site/0izg0f) |
| App 支付 | `alipay.trade.app.pay` | [App 支付文档](https://ideservice.alipay.com/cms/site/0izsn4) |
| 预授权支付 | `alipay.fund.auth.order.app.freeze` | [预授权支付文档](https://ideservice.alipay.com/cms/site/0j0lyx) |
| 商家扣款 | `alipay.trade.app.pay`(支付并签约)+ `alipay.trade.pay`(后续扣款) | [商家扣款文档](https://ideservice.alipay.com/cms/site/0j0g6k) |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall