xinetzone/SpecWeave / .agents/skills/alipay-payment-integration
alipay-payment-integration
Flagged支付宝开放平台支付产品接入最佳实践。涵盖当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款等全场景产品选型与集成指导。 当用户提到"接入支付宝"、"集成支付宝支付"、"对接支付"、"支付宝收款"、"加个支付功能"、"支付宝下单"、"H5 支付"、"小程序支付"、"预授权"、"付款码"、"扫码支付"、"网页支付"、"PC 支付"、"周期扣款"、"自动续费"、"会员订阅"、"连续包月"、"代扣"时,或咨询支付产品相关报错、排查问题时使用此 Skill。
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
- 正式环境涉及真实资金交易,强烈建议在正式上线之前在沙箱环境中完成全链路测试
```
**输出检查:** 确认包含 ⚠️📌🔔🔒 四个标记及全部内容后,方可继续后续集成步骤。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |