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

references/alipay-sandbox/sandbox-setup-guide.md

View on GitHub
# 沙箱环境初始化

## 默认环境说明

**默认使用快速沙箱环境**进行集成,该环境具备以下优势:
- ✅ **零配置启动**:无需登录支付宝开放平台,自动获取测试账号与密钥。
- ✅ **即开即用**:全自动配置网关及应用信息。
- ✅ **安全隔离**:测试环境不涉及真实资金,可放心调试。

## Windows 用户注意事项

**重要提示:** 快速沙箱 CLI 工具目前不支持 Windows 系统。

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

## 密钥格式说明

**私钥格式选择规则**:

| 语言 | 私钥格式 | 使用字段 |
|------|----------|----------|
| JAVA | PKCS#8 | `appPrivateKey` |
| 非 JAVA(Python、Node.js、PHP、.NET 等) | PKCS#1 | `appPrivatePkcsKey` |

**⚠️ 防误判提醒**:
- **禁止手动添加 PEM 头尾**(`-----BEGIN…RSA PRIVATE KEY-----` 等),SDK 自动处理格式
- **禁止因 `ERR_OSSL_UNSUPPORTED` 错误而推断私钥格式有问题**,该错误通常是 SDK 配置参数错误,不是格式问题
- **禁止对私钥值做任何格式处理**(格式转换、编码处理、换行符调整)
- 详见 [SDK 说明文档 - 私钥格式](../main/alipay-sdk-reminder.md)

## 快速沙箱环境配置流程

### 调用工具创建环境

参考 [alipay-sandbox-tool](alipay-sandbox-tool.md) 创建快速沙箱环境并获取返回的环境信息(包含 appId、appPrivateKey、appPrivatePkcsKey、alipayPublicKey、appPublicKey、商家账号、买家账号等)。

**异常处理**:若创建快速沙箱环境失败,提示用户 "❌ 快速沙箱创建失败,请稍后重试"。

### 沙箱信息输出格式

校验通过后,**必须按以下表格格式**向用户输出沙箱信息,**严禁**以 JSON 代码块形式输出。所有字段值必须完整原样展示,不得脱敏、省略或截断。

**应用配置**

| 字段 | 说明 | 值 |
|------|------|-----|
| `appId` | 沙箱应用 ID | {实际返回值} |
| `appPrivateKey` | 应用私钥(PKCS#8,JAVA 语言使用) | {实际返回值} |
| `appPrivatePkcsKey` | 应用私钥(PKCS#1,非 JAVA 语言使用) | {实际返回值} |
| `alipayPublicKey` | 支付宝公钥 | {实际返回值} |
| `appPublicKey` | 应用公钥 | {实际返回值} |
| `pid` | 商户 PID | {实际返回值} |

**商家账号**

| 字段 | 值 |
|------|-----|
| `accountDesc` | {实际返回值} |
| `email` | {实际返回值} |
| `merchantId` | {实际返回值} |
| `userId` | {实际返回值} |
| `acctrans` | {实际返回值} |

**买家账号**

| 字段 | 值 |
|------|-----|
| `accountDesc` | {实际返回值} |
| `email` | {实际返回值} |
| `userName` | {实际返回值} |
| `userId` | {实际返回值} |
| `logonPassword` | {实际返回值} |
| `payPassword` | {实际返回值} |
| `certNo` | {实际返回值} |
| `certType` | {实际返回值} |
| `acctrans` | {实际返回值} |

**沙箱信息**

| 字段 | 值 |
|------|-----|
| `sandboxId` | {实际返回值} |
| `sandboxName` | {实际返回值} |

### 快速沙箱环境信息强校验(卡点)

工具返回环境信息后,**必须执行逐项强校验**,校验通过方可进入后续步骤。未通过则**阻断流程**,要求重新创建。

#### 必含字段清单

以下字段必须全部存在且非空,缺一不可:

| 字段 | 说明 |
|---|---|
| `appId` | 沙箱应用 ID |
| `appPrivateKey` / `appPrivatePkcsKey` | 应用私钥(JAVA 使用 PKCS#8 格式的 `appPrivateKey`,非 JAVA 使用 PKCS#1 格式的 `appPrivatePkcsKey`) |
| `alipayPublicKey` | 支付宝公钥(用于验签) |
| `appPublicKey` | 应用公钥 |
| 商家账号 | 沙箱商家登录账号 |
| 买家账号 | 沙箱买家测试账号 |

#### 🚫 绝对禁止(红线)

**以下行为严格禁止,违者视为严重违规,将直接导致集成失败:**

1. **禁止编造字段** —— 不得以任何方式生成、拼接、模拟、猜测缺失的字段值,所有配置必须来自沙箱工具的实际返回或用户自行提供的真实配置
2. **禁止用占位符冒充真实数据** —— 当沙箱成功返回完整配置时,禁止用占位符(如 `your-app-id-here`、`xxx`)代替真实返回值;当沙箱反复失败,提醒用户**自行申领**或**重新输入创建快速沙箱指令**时,代码中可用占位符标记待填位置,但必须明确告知用户哪些字段需要替换,并标注为待填写
3. **禁止假数据** —— 不得自行生成示例私钥、示例账号等任何假数据
4. **禁止假设存在** —— 不得假设"工具返回的应该都有"而不逐项检查
5. **禁止部分通过** —— 不得因"只有 1 个字段缺失"而继续执行
6. **禁止跳过校验** —— 不得在未完成逐项校验的情况下直接使用返回结果

**违规后果**:产生以上任何一种行为,必须立即停止所有后续步骤,不得输出代码、配置文件或任何集成建议。

#### 校验执行清单(必须按顺序执行)

**规则:** 任一字段缺失或为空 → **立即停止** → 输出错误提示 → **禁止继续**任何后续步骤

```checklist
□ 检查 appId
  IF 缺失或为空:输出 "❌ 沙箱环境校验失败:appId 为空,无法继续集成,请重新创建沙箱环境。" → STOP

□ 检查应用私钥(根据用户使用的语言选择)
  - JAVA 语言:检查 `appPrivateKey`(PKCS#8 格式)
  - 非 JAVA 语言(Python、Node.js、PHP、.NET 等):检查 `appPrivatePkcsKey`(PKCS#1 格式)
  IF 对应字段缺失或为空:输出 "❌ 沙箱环境校验失败:应用私钥字段为空,无法继续集成,请重新创建沙箱环境。" → STOP

□ 检查 alipayPublicKey
  IF 缺失或为空:输出 "❌ 沙箱环境校验失败:alipayPublicKey 为空,无法继续集成,请重新创建沙箱环境。" → STOP

□ 检查 appPublicKey
  IF 缺失或为空:输出 "❌ 沙箱环境校验失败:appPublicKey 为空,无法继续集成,请重新创建沙箱环境。" → STOP

□ 检查商家账号
  IF 缺失或为空:输出 "❌ 沙箱环境校验失败:商家账号为空,无法继续集成,请重新创建沙箱环境。" → STOP

□ 检查买家账号
  IF 缺失或为空:输出 "❌ 沙箱环境校验失败:买家账号为空,无法继续集成,请重新创建沙箱环境。" → STOP

□ 全部通过
  输出 "✅ 沙箱环境校验通过" → 继续下一步:输出成功提示
```

#### 重试与失败处理

**当沙箱创建失败或返回字段缺失时,按以下流程处理:**

1. **首次失败**:提示用户 "❌ 快速沙箱创建失败,请稍后重试",等待用户指示后重新调用工具。
2. **字段缺失**:必须明确告知用户**具体缺失了哪些字段**(如 "appId、appPrivateKey/appPrivatePkcsKey 缺失"),禁止只说"部分字段缺失"而不列出明细。
3. **反复失败(2 次及以上仍缺失字段或创建失败)**:必须输出以下强提醒,**禁止继续自动重试**:

```
🚨 快速沙箱环境多次创建失败/字段不完整

缺失字段:[列出具体缺失的字段名称]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
请您选择以下方式之一解决:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【选项一】重新输入创建快速沙箱指令
  操作方式:在对话中重新输入"创建快速沙箱"或类似指令
  适用场景:可能因服务波动导致创建失败,稍后重试可能成功

【选项二】自行申领沙箱应用
  操作方式:前往支付宝开放平台(https://open.alipay.com)手动申领沙箱应用
  适用场景:需要使用自己的沙箱账号,获取 appId、应用私钥、支付宝公钥等信息后手动配置

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ 在配置完整之前,无法继续集成流程。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

4. **用户提供手动配置后**:仍需按上述「校验执行清单」逐项校验用户提供的配置,校验通过后方可继续。

### 成功创建快速沙箱后提示(卡点)

**⛔ 强制要求:校验通过后,必须在回复中完整输出以下内容,这是阻塞后续步骤的必经卡点。**

- **禁止省略**:不得跳过、缩减或只输出部分内容
- **禁止改写**:必须按原文输出,不得改写措辞
- **未输出此提示即继续后续步骤 = 违规**

```
⚠️ 快速沙箱环境已创建完成

📌 环境说明
- 当前快速沙箱环境仅供测试,不涉及真实资金
- 完整展示沙箱信息,无需对内容脱敏
- 切勿在项目日志中打印私钥信息
- 切勿提交正式环境、沙箱环境信息至公共代码仓库(GitHub、GitLab 等)

🔔 必做操作
- 请自行妥善保管密钥及测试账号等信息

🔒 安全提醒
- 正式上线前请确保您已拥有正式的应用 appId、经过审核的应用私钥及支付宝公钥,并切换至正式环境重新配置密钥
- 正式环境网关地址:https://openapi.alipay.com/gateway.do
- 正式环境涉及真实资金交易,强烈建议在正式上线之前在沙箱环境中完成全链路测试
```

**输出检查:** 确认包含 ⚠️📌🔔🔒 四个标记及全部内容后,方可继续后续集成步骤。
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