@alipay/alipay-aipay 1.0.0 → 1.0.2

package/skill/references/integration/modules/alipay-sdk-reminder.md

@@ -0,0 +1,256 @@
+# Alipay-SDK Reminder
+
+以下各项为接入支付宝 SDK 的相关规则，**严禁在未阅读全部内容的情况下编写任何 SDK 相关代码**。每条规则均来自真实集成踩坑，请逐条阅读并确认后再继续，编写代码遵守规则。
+
+---
+
+## SDK 引入方式
+
+SDK 的引入方式取决于对应语言的包管理方式和实际导出方式，**绝不能凭猜测选择**，必须通过查阅 SDK 文档或类型定义确定。
+
+**各语言 SDK 引入方式参考：**
+
+| 语言 | 包管理 | 引入方式 | 备注 |
+|------|--------|---------|------|
+| Java | Maven | `import com.alipay.api.*;` | 通过 Maven 依赖引入，包结构固定 |
+| .NET | NuGet | `using Aop.Api;` 等 | 通过 NuGet 安装 `AlipaySDKNet.Standard`，命名空间固定 |
+| PHP | Composer | `require_once '../aop/AopClient.php';` 等 | 通过 GitHub 仓库或 Composer 引入，类文件路径以实际目录为准 |
+| Python | pip | `from alipay.aop.api.AlipayClientConfig import AlipayClientConfig`<br>`from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient` | 通过 pip 安装 `alipay-sdk-python`，模块路径以实际版本为准 |
+| Node.js | npm | 需查阅类型定义确认 | 导入方式可能随版本变化，**必须验证**，详见下方「Node.js 导入格式判断」 |
+
+### Node.js 导入格式判断
+
+`alipay-sdk`（Node.js）的导入方式取决于包的实际导出方式，**绝不能凭猜测选择**。
+
+**判断流程：**
+
+1. **查看 package.json**：确认模块类型（ESM/CJS）和入口路径
+   ```bash
+   cat node_modules/alipay-sdk/package.json
+   ```
+   重点看 `type`、`exports`、`main`、`types` 字段。
+
+2. **查看类型定义文件**：确认导出方式
+   ```bash
+   cat node_modules/alipay-sdk/dist/types/index.d.ts
+   ```
+   注意：类型定义文件路径以 package.json 中 `types` 字段为准。
+
+3. **选择导入语法**：
+   - 命名导出（`export class AlipaySdk`）→ `import { AlipaySdk } from 'alipay-sdk'`
+   - 默认导出（`export default`）→ `import AlipaySdk from 'alipay-sdk'`
+   - 混合导出 → `import AlipaySdk, { AlipaySdkConfig } from 'alipay-sdk'`
+
+**优先级**：类型定义（.d.ts）> 官方文档 > 源码
+
+**注意：**
+- package.json 的 `exports` 字段是入口路径配置，不是导出方式
+- 包的导出方式可能随版本更新而改变，务必验证
+
+---
+
+## 页面跳转类 API 方法选择
+
+`alipay.trade.page.pay` 是页面跳转类 API，**严禁使用 `exec()` 方法**，必须使用页面跳转方法。各语言 SDK 的方法名不同，请按下表选择：
+
+| 语言 | 页面跳转方法 | SDK 执行方法 | 页面跳转类 API 举例 |
+|------|-------------|-------------|-------------------|
+| Java | `alipayClient.pageExecute(request, "POST")` | `alipayClient.execute(request)` | `alipay.trade.page.pay` |
+| .NET | `alipayClient.PageExecute(request, null, "POST")` | `alipayClient.Execute(request)` | 同上 |
+| PHP | `$alipayClient->pageExecute($request, "POST")` | `$alipayClient->execute($request)` | 同上 |
+| Node.js | `alipaySdk.pageExec('alipay.trade.page.pay', 'POST', {...})` | `alipaySdk.exec('alipay.trade.query', {...})` | 同上 |
+| Python | `alipay_client.page_execute(request)` | `alipay_client.execute(request)` | 同上 |
+
+**此外，APP支付（`alipay.trade.app.pay`）属于客户端 SDK 调用类 API，需使用 `sdkExecute`/`sdkExec` 方法：**
+
+| 语言 | 客户端 SDK 方法 |
+|------|---------------|
+| Java | `alipayClient.sdkExecute(request)` |
+| .NET | `alipayClient.SdkExecute(request)` |
+| PHP | `$alipayClient->sdkExecute($request)` |
+| Node.js | `alipaySdk.sdkExecute('alipay.trade.app.pay', {...})` |
+
+**Node.js 对比示例：**
+```javascript
+// ✅ 正确 - 页面跳转类 API 使用 pageExec()
+const htmlForm = alipaySdk.pageExec('alipay.trade.page.pay', 'POST', {
+  bizContent: { out_trade_no: '123', total_amount: '10.00', ... }
+});
+// 返回：<form action="...">...</form> HTML 字符串
+
+// ❌ 错误 - 对页面跳转类 API 使用 exec()
+const result = await alipaySdk.exec('alipay.trade.page.pay', {
+  bizContent: { out_trade_no: '123', total_amount: '10.00', ... }
+});
+// 返回：JSON 对象，无法用于页面跳转，这是最常见的集成错误！
+```
+
+| 方法类型 | 用途 | 返回值 | 示例 |
+| --- | --- | --- | --- |
+| 页面跳转方法（`pageExec()`/`pageExecute()` 等） | 页面跳转类 API（如：支付） | HTML 表单字符串 | 网站支付 |
+| `exec()` | 服务端 API（查询 / 退款） | 结构化数据（JSON 等） | 交易查询、退款 |
+
+**对支付接口调用 exec() 将不会得到可用的支付表单，是最常见的集成错误之一。**
+
+### 前端支付表单处理
+
+页面跳转类 API 返回的是包含自动提交脚本的 HTML `<form>` 字符串，前端**必须将此 HTML 渲染到页面并自动提交表单**，禁止直接用 URL 跳转。
+
+**❌ 错误写法（以浏览器端 JavaScript 为例）**：
+```javascript
+// paymentHtml 是 HTML 表单字符串，不是 URL
+if (data.paymentHtml) {
+  window.location.href = data.paymentHtml; // 页面只显示 ?method=alipay.trade.page.pay... 参数，无法跳转
+}
+```
+
+**✅ 正确写法**：
+```javascript
+if (data.paymentHtml) {
+  const container = document.createElement('div');
+  container.innerHTML = data.paymentHtml;
+  container.style.position = 'fixed';
+  container.style.top = '0';
+  container.style.left = '0';
+  container.style.width = '100%';
+  container.style.height = '100%';
+  container.style.zIndex = '9999';
+  container.style.background = 'white';
+  document.body.appendChild(container);
+  const form = container.querySelector('form');
+  if (form) form.submit();
+}
+```
+
+---
+
+## 私钥格式
+
+**沙箱返回两个私钥字段，必须按语言选对：**
+
+| 字段 | 格式 | 使用场景 |
+|------|------|---------|
+| `appPrivateKey` | PKCS#8 格式 | ✅ Java 语言必须使用 |
+| `appPrivatePkcsKey` | PKCS#1 格式 | ✅ 非 Java 语言（Python、Node.js、PHP、.NET 等）必须使用 |
+
+**严禁以下误判行为：**
+
+| 误判行为 | 为什么错 | 正确做法 |
+|---------|---------|---------|
+| 看到 `ERR_OSSL_UNSUPPORTED` 就推断私钥格式有问题 | 该错误通常是 SDK 配置参数错误（如私钥字段选错、字符编码问题），**不是**私钥格式本身有问题 | 先确认使用了正确的私钥字段（Java 用 `appPrivateKey`，非 Java 用 `appPrivatePkcsKey`），再检查其他配置参数 |
+| 手动添加 PEM 头尾、其他前后缀、包装行或说明文字 | 支付宝 SDK 会按配置自行处理密钥包装，手动添加会导致格式错误 | 直接使用沙箱或生产配置中的原始私钥值，不做任何格式处理 |
+| 将沙箱返回的 `appPrivatePkcsKey` 转换为 PKCS#8 格式 | 沙箱已同时返回两种格式，转换会引入不必要风险 | 非 Java 语言使用原始 `appPrivatePkcsKey` 值，不做转换 |
+| 将沙箱返回的 `appPrivateKey` 转换为 PKCS#1 格式 | 沙箱已同时返回两种格式，转换会引入不必要风险 | Java 语言使用原始 `appPrivateKey` 值，不做转换 |
+| 对私钥内容做 Base64 解码/重新编码 | 无需任何编码处理 | 直接使用沙箱返回的原始字符串 |
+| 因为字段名含 "Pkcs" 就认为是 PKCS#8 格式 | `appPrivatePkcsKey` 是 **PKCS#1** 格式，"Pkcs" 仅表示这是 PKCS 系列标准之一，不代表 PKCS#8 | 非 Java 语言使用 `appPrivatePkcsKey`（PKCS#1），Java 语言使用 `appPrivateKey`（PKCS#8） |
+
+**核心原则：沙箱配置直接使用沙箱返回的对应私钥字段，不做格式转换；生产配置必须确认应用私钥格式与项目语言匹配。所有写入 SDK 配置的私钥值都使用不带 PEM 头尾或其他前后缀的原始密钥字符串，禁止手动添加 PEM 头尾、添加其他前后缀、编码处理或换行符调整。Java 语言使用 PKCS#8，非 Java 语言（Node.js、Python、PHP、.NET 等）使用 PKCS#1。**
+
+### 生产密钥替换与生产支付测试提醒
+
+当用户要求 Agent 直接替换生产环境密钥配置，或用户声称已经替换完成并要求启动生产环境支付测试时，必须先提醒并核对以下事项：
+
+1. `appId`、应用公钥、应用私钥必须属于同一套生产应用密钥，不得混用沙箱应用、其他生产应用或另一套重新生成的密钥。
+2. 基于项目编程语言确认应用私钥格式：Java 使用 PKCS#8；非 Java（Node.js、Python、PHP、.NET 等）使用 PKCS#1。
+3. 如果生产应用私钥格式与当前语言 SDK 要求不一致，请使用支付宝开放平台密钥工具进行私钥格式转换，再将转换后的原始私钥字符串写入项目配置。
+4. 不得把私钥输出到日志、对话总结、测试结果或完整支付表单中。
+
+### 连环误判链
+
+遇到 `ERR_OSSL_UNSUPPORTED` 时，agent 容易陷入以下**越错越远**的连环推理，**每一步都是错的**，必须识别并阻断：
+
+```
+❌ 连环误判链（严禁陷入）：
+
+第 1 步（误判起点）：看到 ERR_OSSL_UNSUPPORTED → 推断"私钥格式有问题"
+    ↓
+第 2 步（错误修复）：认为"PKCS#1 私钥应该手动添加 PEM 头尾或其他前后缀"
+    → 手动添加 PEM 头尾或其他前后缀 → 错误仍在
+    ↓
+第 3 步（错误归因）：认为"Node.js 18+ 用了 OpenSSL 3.0，旧格式不被支持"
+    ↓
+第 4 步（越错越远）：认为"应该把原始私钥改成另一种格式"
+    → 将私钥转换为 PKCS#8 格式 → 错误更严重（注：Java 语言应直接使用沙箱返回的 `appPrivateKey` 字段，而非手动转换格式）
+```
+
+**正确做法**：看到 `ERR_OSSL_UNSUPPORTED`，**立即停止所有格式操作**，按下方「验签失败排查原则」中的正确排查顺序逐项检查。
+
+---
+
+## 验签失败排查原则
+
+遇到 `invalid-signature`（验签出错）时，**严禁凭猜测归因到私钥格式或环境兼容性**，必须按以下顺序逐项排查：
+
+### 正确排查顺序
+
+**原则：先验证实际请求内容，再怀疑密钥配置。**
+
+1. **检查请求参数完整性**（最常见原因）
+   - 支付宝验签时校验所有请求参数是否匹配。如果 `return_url`、`notify_url` 等参数在配置中定义但未传入支付请求，或传入但未参与签名，将导致验签失败。
+   - **排查方法**：打印或检查实际发送给支付宝的请求参数，确认 `return_url`、`notify_url` 等参数是否正确包含在请求中。
+   ```bash
+   # 检查实际请求中是否包含 return_url
+   # 在服务端日志中打印请求参数，确认 return_url 存在
+   ```
+
+2. **检查私钥来源**
+   - 确认使用的是沙箱返回的正确私钥字段：Java 使用 `appPrivateKey`，非 Java 使用 `appPrivatePkcsKey`，而非自行生成或其他来源。
+
+3. **检查 signType 是否一致**
+   - 请求中的 `sign_type` 必须为 `RSA2`，与配置保持一致。
+
+4. **检查私钥格式完整性**
+   - 私钥内容无多余空格、换行符。
+
+5. **检查网关地址**
+   - 沙箱环境必须使用沙箱网关 `https://openapi-sandbox.dl.alipaydev.com/gateway.do`，生产环境使用 `https://openapi.alipay.com/gateway.do`。
+
+> **核心教训**：验签失败 ≠ 私钥问题。应先通过日志/输出验证实际请求行为（参数是否完整传入），而非基于技术传言做假设。
+
+---
+
+## 时间戳格式化
+
+支付宝要求时间戳格式为 `yyyy-MM-dd HH:mm:ss`（空格分隔，非 ISO 格式）。
+
+### Java
+```java
+import java.text.SimpleDateFormat;
+// ✅ 正确
+new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date());
+// ❌ 错误：Instant.now().toString() → "2026-04-29T14:30:00.000Z"
+```
+
+### .NET (C#)
+```csharp
+// ✅ 正确
+DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
+// ❌ 错误：DateTime.Now.ToString("o") → "2026-04-29T14:30:00.0000000+08:00"
+```
+
+### PHP
+```php
+// ✅ 正确
+date("Y-m-d H:i:s");
+// ❌ 错误：date("c") → "2026-04-29T14:30:00+08:00"
+```
+
+### Node.js
+```javascript
+function formatAlipayTimestamp(date) {
+  const pad = (n) => n.toString().padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+// ❌ 错误：new Date().toISOString() → "2026-04-29T14:30:00.000Z"
+```
+
+### Python
+```python
+from datetime import datetime
+
+def format_alipay_timestamp(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+# ❌ 错误：datetime.isoformat() → "2026-04-29T14:30:00"
+```

package/skill/references/integration/modules/checklist.md

@@ -0,0 +1,122 @@
+# 支付宝支付集成校验清单
+
+本文档整理了支付宝支付集成过程中的通用校验项，仅包含必须校验和高危项目。集成完成后，请逐项核对并通过校验模板输出结果。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。
+
+---
+
+## 一、密钥与安全校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 私钥存储位置 | 私钥不得保存在客户端代码中 | 构造交易数据并签名必须在商家服务端完成，私钥绝对不能保存在商家APP客户端中，也不能从服务端下发。商户需妥善保存私钥，不建议在代码或配置中明文写入私钥，应当通过加密配置文件或秘钥管理平台进行管理 |
+| 私钥日志安全 | 私钥不得出现在日志中 | 私钥的保密等级比源码高，出现在日志中将增加私钥泄露的风险 |
+| 私钥仓库安全 | 私钥不得上传公共仓库 | 私钥泄露将导致应用和支付宝交互的安全性完全丧失 |
+| 沙箱配置后置校验 | 沙箱 appId、应用私钥、支付宝公钥写入项目后必须完成配置准确性校验 | 必须确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段选择正确、SDK 配置匹配，私钥不是占位符、示例值或其他来源的密钥 |
+
+---
+
+## 二、异步通知校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 验签必须执行 | 收到异步通知后必须先验签 | 确保通知来自支付宝 |
+| 关键信息校验 | 检验 out_trade_no、total_amount、app_id、seller_id 等商户请求关键参数| 防止伪造订单、金额篡改等 |
+| 交易状态判断 | 仅 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 才算支付成功 | 其他状态不算支付成功 |
+| 幂等处理 | 必须进行幂等处理，过滤重复的通知 | 同一笔订单可能收到多次异步通知 |
+| 响应值 | 商户侧处理成功后需返回字符串 `success` | 否则支付宝会重试通知 |
+| URL 格式 | notify_url 不能包含空格和 HTML 标签 | 否则可能导致通知失败 |
+| 重定向 | notify_url 不能重定向 | 重定向会导致支付宝收不到 success |
+| 外网可访问 | notify_url 必须外网可访问 | 需确保支付宝服务器可访问 |
+
+---
+
+## 三、支付结果处理校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 前台同步结果防范 | 前台同步跳转结果仅作通知，**不能作为支付成功的依据** | 必须以异步通知或查询接口结果为准 |
+| 支付成功判断 | 仅 `trade_status` 为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时才认定付款成功 | 其他状态不算支付成功 |
+| 主动查询兜底 | 主动查询订单状态必须作为支付结果确认的兜底逻辑 | 无论异步通知是否到达，都应具备主动查询订单状态的能力，防止因网络抖动、通知延迟或丢失导致的状态不一致 |
+| 未知异常处理 | 网络超时或未知异常时，必须调用查询接口确认 | 不能简单推断为成功或失败 |
+| 商家资损防范 | 不依赖前台同步结果，以异步通知或查询为准 | 防止用户未付款但商家判定成功 |
+| 用户资损防范 | 未确认支付结果前不要求用户再次付款 | 防止用户已付款但商家判定失败导致重复扣款 |
+
+> 按量付费不使用前台同步跳转结果和异步通知作为支付成功依据，需按下一节专项校验。
+
+---
+
+## 四、按量付费专项校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 订单持久化 | 返回 `Payment-Needed` 前必须持久化 `out_trade_no`、`resource_id`、金额、状态、过期时间 | 付款后携带 `Payment-Proof` 回来时必须能映射回商户本地订单 |
+| Payment-Proof 验证 | 收到 `Payment-Proof` 后必须调用 `alipay.aipay.agent.payment.verify` | 验证成功只代表支付宝凭证有效，不代表本地订单已完成校验 |
+| 本地订单匹配 | 验付成功后必须查询本地订单并校验状态 | 防止凭证有效但商户订单不存在、过期或状态异常 |
+| 资源防串 | 必须校验本地订单的 `resource_id` 与验付结果/请求资源一致 | 防止用户通过篡改资源标识获取其他资源 |
+| 金额一致性 | 必须校验本地订单金额与 `Payment-Needed` 账单金额和服务定价一致；若验付接口返回金额字段，再校验实际支付金额 | 防止金额篡改或错误定价 |
+| 幂等履约 | 同一订单重复携带 `Payment-Proof` 时不得重复发放资源 | 应返回历史履约结果或可重试确认结果 |
+| 履约确认 | 资源生成后必须调用 `alipay.aipay.agent.fulfillment.confirm` | 确认成功后再标记订单 `FULFILLED` 并返回成功交付 |
+| 沙箱空字段边界 | 沙箱联调中字段为空可用于排查定位，生产环境关键字段为空必须按异常处理 | 不得把沙箱容错逻辑直接迁移成生产跳过校验 |
+
+---
+
+## 五、退款校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 退款使用场景 | 所有退款业务都必须调用退款接口 | 撤销接口不能用于退款业务，撤销接口仅用于在不确定支付结果情况下对交易发起撤销 |
+| 退款是否成功判断 | 退款接口返回 `fund_change=Y` 或退款查询返回 `refund_status=REFUND_SUCCESS` 才算退款成功 | 其他状态不算退款成功 |
+| 退款幂等保障 | 接口未退款成功且不明确交易情况时，重试请务必保证退款请求号 out_request_no 以及请求参数一致，避免发生多次退款 | 防止多次退款 |
+
+---
+
+## 六、上线前校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 网关地址切换 | 切换为生产网关 `https://openapi.alipay.com/gateway.do`|  上线前必须修改 |
+| APPID 切换 | 使用生产环境的 APPID | 与沙箱 APPID 不同 |
+| 密钥切换 | 使用生产环境的应用私钥和支付宝公钥 | 与沙箱密钥不同 |
+| 生产密钥对应关系 | `appId`、应用公钥、应用私钥属于同一套生产应用密钥 | 不得混用沙箱应用、其他生产应用或另一套重新生成的密钥 |
+| 生产私钥格式 | 应用私钥格式与项目语言 SDK 匹配 | Java 使用 PKCS#8；非 Java 使用 PKCS#1。格式不匹配时使用支付宝开放平台密钥工具转换 |
+| 证书切换 | 公钥证书模式需切换为生产环境证书 | 应用公钥证书、支付宝公钥证书、支付宝根证书 |
+| 产品开通状态 | 确认产品已在生产环境开通 | 沙箱无需开通，生产环境需要申请开通 |
+| 私钥安全 | 私钥不在代码、日志、公共仓库中明文存储 | 使用安全的方式管理私钥 |
+| 日志安全 | 日志中不打印敏感信息（私钥、用户信息等） | 防止信息泄露 |
+| HTTPS 通信 | 生产环境必须使用 HTTPS | 保证传输安全 |
+
+---
+
+## 七、集成结果校验模板
+
+> 复制以下模板，逐项填写校验结果并输出。校验结果说明：
+> - ✅ 通过：已实现且符合规范
+> - ❌ 不通过：未实现或不符合规范，需整改
+> - ⚠️ 部分通过：部分实现，需补充完善
+> - ➖ 不适用：当前集成场景不涉及此项
+
+### 一、校验结论
+[校验结果整体结论，输出校验结果和风险情况]
+---
+
+### 二、校验清单
+
+| 校验类别 | 校验项 | 校验结果 | 问题描述 |
+|------|------|------|------|
+| 密钥与安全校验 | | | |
+| 异步通知校验 | | | |
+| 支付结果处理校验 | | | |
+| 按量付费专项校验 | | | |
+| 退款校验 | | | |
+| 上线前校验 | | | |
+| **合计** | | | |
+
+---
+
+### 三、风险说明
+
+[未通过校验项（❌不通过、⚠️部分通过）的风险说明，需要提醒用户发布前完成整改或确认风险可接受。]
+
+---
+
+> 📖 本文档内容整理自支付宝开放平台官方文档，如有更新请以官方文档为准。

package/skill/references/integration/modules/code-examples/csharp/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/345/205/263/351/227/255/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,68 @@
+# 统一收单交易关闭接口 - C# 示例
+
+## 请求示例
+
+```csharp
+using Aop.Api;
+using Aop.Api.Request;
+using Aop.Api.Response;
+using Aop.Api.Domain;
+
+// 初始化SDK（C#/.NET 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
+
+var request = new AlipayTradeCloseRequest();
+var model = new AlipayTradeCloseModel
+{
+    OutTradeNo = "MERCHANT_ORDER_NO_PLACEHOLDER",  // 商户订单号，与 TradeNo 二选一
+    // TradeNo = "ALIPAY_TRADE_NO_PLACEHOLDER",  // 支付宝交易号，同时传时以 TradeNo 为准
+};
+request.SetBizModel(model);
+
+AlipayTradeCloseResponse response = alipayClient.Execute(request);
+
+if (!response.IsError)
+{
+    Console.WriteLine("交易关闭成功");
+}
+else
+{
+    Console.WriteLine($"调用失败: {response.SubCode} - {response.SubMsg}");
+}
+
+private static AlipayConfig GetAlipayConfig()
+{
+    string privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+    string alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+    AlipayConfig alipayConfig = new AlipayConfig();
+    alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do";
+    // 沙箱环境: alipayConfig.ServerUrl = "https://openapi-sandbox.dl.alipaydev.com/gateway.do";
+    alipayConfig.AppId = "<-- 请填写您的AppId，例如：20190xxxxxx -->";
+    alipayConfig.PrivateKey = privateKey;
+    alipayConfig.Format = "json";
+    alipayConfig.AlipayPublicKey = alipayPublicKey;
+    alipayConfig.Charset = "UTF-8";
+    alipayConfig.SignType = "RSA2";
+    return alipayConfig;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill/references/integration/modules/code-examples/csharp/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/346/237/245/350/257/242/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,77 @@
+# 统一收单交易查询接口 - C# 示例
+
+## 请求示例
+
+```csharp
+using Aop.Api;
+using Aop.Api.Request;
+using Aop.Api.Response;
+using Aop.Api.Domain;
+
+// 初始化SDK（C#/.NET 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
+
+var request = new AlipayTradeQueryRequest();
+var model = new AlipayTradeQueryModel
+{
+    OutTradeNo = "MERCHANT_ORDER_NO_PLACEHOLDER",  // 商户订单号，与 TradeNo 二选一
+    // TradeNo = "ALIPAY_TRADE_NO_PLACEHOLDER",  // 支付宝交易号，同时传时以 TradeNo 为准
+};
+request.SetBizModel(model);
+
+AlipayTradeQueryResponse response = alipayClient.Execute(request);
+
+if (!response.IsError)
+{
+    // trade_status: TRADE_SUCCESS/TRADE_FINISHED 表示支付成功，TRADE_CLOSED 表示已关闭
+    Console.WriteLine($"交易状态: {response.TradeStatus}");
+    Console.WriteLine($"订单金额: {response.TotalAmount}");
+}
+else
+{
+    Console.WriteLine($"调用失败: {response.SubCode} - {response.SubMsg}");
+}
+
+private static AlipayConfig GetAlipayConfig()
+{
+    string privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+    string alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+    AlipayConfig alipayConfig = new AlipayConfig();
+    alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do";
+    // 沙箱环境: alipayConfig.ServerUrl = "https://openapi-sandbox.dl.alipaydev.com/gateway.do";
+    alipayConfig.AppId = "<-- 请填写您的AppId，例如：20190xxxxxx -->";
+    alipayConfig.PrivateKey = privateKey;
+    alipayConfig.Format = "json";
+    alipayConfig.AlipayPublicKey = alipayPublicKey;
+    alipayConfig.Charset = "UTF-8";
+    alipayConfig.SignType = "RSA2";
+    return alipayConfig;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER",
+    "trade_status": "TRADE_SUCCESS",
+    "total_amount": "88.88",
+    "buyer_pay_amount": "8.88",
+    "receipt_amount": "15.25",
+    "buyer_logon_id": "159****5620",
+    "buyer_user_id": "<BUYER_USER_ID>",
+    "send_pay_date": "2014-11-27 15:45:57"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill/references/integration/modules/code-examples/csharp/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/351/200/200/346/254/276/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,74 @@
+# 统一收单交易退款接口 - C# 示例
+
+## 请求示例
+
+```csharp
+using Aop.Api;
+using Aop.Api.Request;
+using Aop.Api.Response;
+using Aop.Api.Domain;
+
+// 初始化SDK（C#/.NET 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
+
+var request = new AlipayTradeRefundRequest();
+var model = new AlipayTradeRefundModel
+{
+    OutTradeNo = "MERCHANT_ORDER_NO_PLACEHOLDER",   // 商户订单号，与 TradeNo 二选一
+    RefundAmount = "200.12",            // 退款金额，必填，单位为元
+    RefundReason = "正常退款",           // 退款原因，选填
+    OutRequestNo = "OUT_REQUEST_NO_PLACEHOLDER",         // 退款请求号，同一笔交易多次部分退款时必填且必须不同
+};
+request.SetBizModel(model);
+
+AlipayTradeRefundResponse response = alipayClient.Execute(request);
+
+if (!response.IsError)
+{
+    // fund_change: Y=发生了资金变化（退款成功），N=未发生资金变化
+    Console.WriteLine($"资金变化: {response.FundChange}, 退款金额: {response.RefundFee}");
+}
+else
+{
+    Console.WriteLine($"调用失败: {response.SubCode} - {response.SubMsg}");
+}
+
+private static AlipayConfig GetAlipayConfig()
+{
+    string privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+    string alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+    AlipayConfig alipayConfig = new AlipayConfig();
+    alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do";
+    // 沙箱环境: alipayConfig.ServerUrl = "https://openapi-sandbox.dl.alipaydev.com/gateway.do";
+    alipayConfig.AppId = "<-- 请填写您的AppId，例如：20190xxxxxx -->";
+    alipayConfig.PrivateKey = privateKey;
+    alipayConfig.Format = "json";
+    alipayConfig.AlipayPublicKey = alipayPublicKey;
+    alipayConfig.Charset = "UTF-8";
+    alipayConfig.SignType = "RSA2";
+    return alipayConfig;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER",
+    "buyer_logon_id": "159****5620",
+    "fund_change": "Y",
+    "refund_fee": "88.88"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill/references/integration/modules/code-examples/csharp/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/351/200/200/346/254/276/346/237/245/350/257/242/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,73 @@
+# 统一收单交易退款查询接口 - C# 示例
+
+## 请求示例
+
+```csharp
+using Aop.Api;
+using Aop.Api.Request;
+using Aop.Api.Response;
+using Aop.Api.Domain;
+
+// 初始化SDK（C#/.NET 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
+
+var request = new AlipayTradeFastpayRefundQueryRequest();
+var model = new AlipayTradeFastpayRefundQueryModel
+{
+    OutTradeNo = "MERCHANT_ORDER_NO_PLACEHOLDER",   // 商户订单号，与 TradeNo 二选一
+    OutRequestNo = "OUT_REQUEST_NO_PLACEHOLDER",         // 退款请求号，必填，同一笔交易多次部分退款时用于区分
+};
+request.SetBizModel(model);
+
+AlipayTradeFastpayRefundQueryResponse response = alipayClient.Execute(request);
+
+if (!response.IsError)
+{
+    // refund_status: REFUND_SUCCESS 表示退款成功，REFUND_PROCESSING 表示退款处理中
+    Console.WriteLine($"退款状态: {response.RefundStatus}, 退款金额: {response.RefundAmount}");
+}
+else
+{
+    Console.WriteLine($"调用失败: {response.SubCode} - {response.SubMsg}");
+}
+
+private static AlipayConfig GetAlipayConfig()
+{
+    string privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+    string alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+    AlipayConfig alipayConfig = new AlipayConfig();
+    alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do";
+    // 沙箱环境: alipayConfig.ServerUrl = "https://openapi-sandbox.dl.alipaydev.com/gateway.do";
+    alipayConfig.AppId = "<-- 请填写您的AppId，例如：20190xxxxxx -->";
+    alipayConfig.PrivateKey = privateKey;
+    alipayConfig.Format = "json";
+    alipayConfig.AlipayPublicKey = alipayPublicKey;
+    alipayConfig.Charset = "UTF-8";
+    alipayConfig.SignType = "RSA2";
+    return alipayConfig;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER",
+    "out_request_no": "OUT_REQUEST_NO_PLACEHOLDER",
+    "total_amount": "100.20",
+    "refund_amount": "12.33",
+    "refund_status": "REFUND_SUCCESS"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```