---
name: wechatpay-basic-payment
description: 微信支付基础支付解决方案，涵盖支付、退款账单、分账、商户进件、开户意愿确认，提供选型/代码示例/业务速查/质量评估/排障五大能力。Use when user mentions "JSAPI支付", "APP支付", "H5支付", "Native支付", "小程序支付", "付款码支付", "合单支付", "特约商户进件", "开户意愿确认", or asks to "推荐支付方式", "要支付接口代码示例", "排查支付或退款问题".
author: wechatpay
version: "1.0"
---

# 微信支付基础支付 & 合单支付接入指引

## 全局交互规范

> ‼️ 以下规则适用于本技能所有能力、所有对话轮次，优先级高于各能力的局部规则。

1. **所有问题必须得到用户明确回答后才能继续。** 如果一次提出了多个问题，必须逐一检查每个问题是否都已获得用户的明确答复。对于未回答的问题，必须再次追问，**严禁对未回答的问题自行假设、推断或使用默认值**。
2. **接入模式前置确认**：任何能力使用前须先确认**商户模式**或**服务商模式**，已明确则无需重复。两种模式的核心差异见 → [📄 接入模式说明.md](./references/3-商户与服务商通用/接入指南/接入模式说明.md)。
3. **分步确认协议**（简单知识问答除外，需要帮用户排查、分析或执行操作时必须遵守）：
  - **① 明确需求**：先理解用户问题，给出初步判断或原因分析，不要一上来就堆参数清单。
  - **② 征得同意**：主动提出下一步能做什么，**等用户明确同意后**才继续，严禁用户没表态就开始收集参数或执行操作。
  - **③ 收集信息**：用户同意后再告知需要哪些信息并逐项收集，收齐才能执行。
  - **④ 执行前确认**：准备执行操作前，简要说明即将做什么，确认用户同意后再执行；涉及线上环境须额外提示风险。

## 能力概览

1. **产品选型** — 根据场景推荐支付方式（JSAPI/APP/H5/Native/小程序/付款码），判断是否需要合单支付
2. **示例代码** — 各接口的下单、调起、回调、退款、账单等代码结构示例（只展示不写入）
3. **业务知识速查** — 订单状态、退款规则、账单对账、APPID绑定、特约商户进件、开户意愿确认等
4. **接入质量评估** — 签名验签、业务逻辑完整性、回调处理规范性检查（含合单/分账/进件/开户意愿确认专项）
5. **问题排查** — 下单失败、调起异常、回调收不到、退款失败等（含合单支付专项常见问题）

> 未明确支付方式时先通过能力1引导选型。退款和账单无需确认支付方式，但仍需确认接入模式。合单支付需先确认是否涉及多商户/多APPID场景。特约商户进件和商户开户意愿确认仅适用于服务商/渠道商模式。

## 能力1：产品选型

> 用户问「该用哪种支付方式」或比较各方式区别时 → 加载 `支付产品对比.md`，确定支付方式后再按需加载示例代码。

- 产品对比 + 选型决策树 + 准入条件 + 调起支付差异 → [📄 支付产品对比.md](./references/3-商户与服务商通用/产品选型/支付产品对比.md)

## 能力2：示例代码

> 用户要某个接口的代码示例时 → 确认接入模式和语言，加载对应模式的 `接口索引.md` 定位代码文件。
>
> ‼️ **只检索、不生成。** 严禁从零编写任何代码，必须从代码示例文件中检索获取。
>
> ‼️ **只展示、不写入。** 代码示例仅用于讲解 API 调用结构和签名流程，严禁直接写入用户项目（禁止调用 write_to_file、replace_in_file 等工具创建或修改项目文件）。在对话中展示代码，让用户自行复制适配。
>
> ‼️ **先交互、后输出。** 提供代码前必须先确认接入模式、开发语言和具体接口，每次只输出一个接口；提供完代码后主动推荐接入质量评估。
>
> ‼️ **支付方式仅「下单」和「调起支付」接口需确认，其他接口无需询问支付方式。** 用户请求查单、关单、退款、回调处理、账单等通用接口时，只需确认接入模式和开发语言，无需询问支付方式——这些接口各支付方式完全相同。**但合单支付的查单、关单、回调使用专用接口，需确认用户是基础支付还是合单支付。**
>
> ‼️ **用户语言非 Java/Go 时**（本 skill 仅维护 Java/Go 示例）：**禁止**直接生成跨语言代码。流程：
> 1. 用 `AskQuestion` 获明确同意（文案需明示「参考实现 / 非官方维护 / 须自行 review 与测试」），未同意只发官方 Java/Go 原文。
> 2. 同意后以官方 Java 示例为基准翻译生成业务代码「参考实现」；再用纯文字问是否翻 Java 公库（SDK 工具类 + HTTP 客户端），未明确要不贴。每段代码前附下方免责块。
>
> > ⚠️ 以下代码为**跨语言参考实现**，由 AI 参考官方 Java 示例翻译生成，并非微信支付官方维护。
> > - 请**逐行 review** 签名构造、HTTP 调用、字段命名、回调解密等关键逻辑。
> > - 上线前必须在测试环境完整验证，建议先以官方 Java/Go 示例打通主链路作为对照。
> > - 出现接入问题时以官方 Java/Go 示例为准。

- 涉及提供示例代码时，按接入模式查阅对应接口索引，定位目标代码文件：
  - 商户模式 → [📄 接口索引.md](./references/1-商户/示例代码/接口索引.md)
  - 服务商模式 → [📄 接口索引.md](./references/2-服务商/示例代码/接口索引.md)

> **加载策略**：先确认接入模式，读对应的 `接口索引.md` 定位用户需要的接口对应的文件路径，再按需加载具体文件。不要一次性加载所有文件。

## 能力3：业务知识速查

> 用户问参数获取、APPID绑定、订单状态、退款规则、分账等业务知识时 → 按接入模式加载对应文档。

- 开发必要参数 / APPID类型 / APPID绑定流程：
  - 商户模式 → [📄 开发必要参数说明.md](./references/1-商户/接入指南/开发必要参数说明.md)
  - 服务商模式 → [📄 开发必要参数说明.md](./references/2-服务商/接入指南/开发必要参数说明.md)
- 点金计划（服务商 JSAPI 必接） → [📄 点金计划.md](./references/2-服务商/接入指南/点金计划.md)
- 订单状态 / 关单 / 终态 → [📄 订单状态流转.md](./references/3-商户与服务商通用/接入指南/订单状态流转.md)
- 分账 → [📄 分账接入指南.md](./references/3-商户与服务商通用/接入指南/分账接入指南.md)
- 特约商户进件（仅服务商） → [📄 特约商户进件.md](./references/2-服务商/接入指南/特约商户进件.md)
- 商户开户意愿确认（仅服务商/渠道商） → [📄 商户开户意愿确认.md](./references/2-服务商/接入指南/商户开户意愿确认.md)
- 退款规则 / 账单对账 → 已整合到示例代码注释中，通过能力2加载

> **加载策略**：按关键词匹配文档，区分接入模式。特约商户进件和商户开户意愿确认为服务商/渠道商专属，商户模式无需加载。

## 能力4：接入质量评估

> 用户准备上线或想检查代码隐患时 → 加载以下文档。
>
> ‼️ **只检查用户实际使用的功能模块。** 合单支付、分账、进件、开户意愿确认等模块须先确认用户是否涉及，**未使用的不检查、不提及**。

- 签名验签 → [📄 签名与验签规则.md](./references/3-商户与服务商通用/接入指南/签名与验签规则.md)
- 业务逻辑完整性（含质检人设 + 检查清单） → [📄 接入质量检查清单.md](./references/3-商户与服务商通用/接入指南/接入质量检查清单.md)
- 回调处理规范 → [📄 回调通知处理.md](./references/3-商户与服务商通用/接入指南/回调通知处理.md)

## 能力5：问题排查

> 用户遇到报错或接口调用异常时 → 按下方路径分流加载。
>
> ‼️ **排障推荐示例代码时，必须先确认开发语言，只推荐对应的示例。** 排障手册中每个错误码的「示例代码推荐」可能涉及 Java/Go 两种语言示例，但输出时**只输出匹配的示例**。开发语言尚未确认时，先在推荐示例代码时自然地询问用户。
>
> ‼️ **用户语言非 Java/Go 时按能力 2 的跨语言确认流程处理**（弹框确认 → 参考生成 + 免责块 + 公库分步）。先用文字说明 Java/Go 示例中的关键修复点（签名、字段、流程），再走完整流程后再生成对应语言的"参考修复代码"。

- 排障手册（错误码 TOP 20 速查 + 定位流程 + 服务商特有问题）→ [📄 排障手册.md](./references/3-商户与服务商通用/问题排查/排障手册.md)
- 基础支付常见问题 → [📄 基础支付常见问题.md](./references/3-商户与服务商通用/问题排查/基础支付常见问题.md)
- 分账常见问题 → [📄 分账常见问题.md](./references/3-商户与服务商通用/问题排查/分账常见问题.md)
- 合单支付常见问题 → [📄 合单支付常见问题.md](./references/3-商户与服务商通用/问题排查/合单支付常见问题.md)
- 排障辅助脚本（排障手册中 🔧 标注的场景）：`scripts/商户/` 和 `scripts/服务商/` 下各有 `查询订单.py`、`查询退款.py`

> **加载策略**：
>
> - **路径A（有 Request-Id）**→ 读 `排障手册.md`，提取错误码匹配 TOP 20 速查表直接给出方案；标注 🔧 的引导用户执行脚本。未命中则按手册各章节排查，仍未解决再加载对应常见问题文档兜底。
> - **路径B（无 Request-Id）**→ 确认支付方式，加载对应常见问题文档匹配。未命中再加载 `排障手册.md` 兜底。
> - **路径C（进件/开户意愿确认）**→ 直接加载 `特约商户进件.md` 或 `商户开户意愿确认.md`，文档末尾的常见问题和常见报错覆盖高频问题。
>
> **脚本使用规范**：脚本采用签名模式，不获取用户私钥。引导用户在自己服务器完成签名后，将签名值（Base64）、时间戳、随机串传入脚本。执行前需按分步确认协议征得同意。

---

> 以下信息与技能能力无关，仅供查阅。

## 💬 社区与反馈

在使用过程中遇到问题、有改进建议，或者想和其他开发者交流接入经验，欢迎扫码添加企业微信进群，与官方团队和社区开发者一起讨论：

![微信支付 Skills 交流群二维码](https://raw.githubusercontent.com/wechatpay-apiv3/wechatpay-skills/main/wechatpay-basic-payment/assets/qrcode.jpg)