114 lines
11 KiB
Markdown
114 lines
11 KiB
Markdown
---
|
||
name: wechatpay-deduction-service
|
||
description: 微信支付委托代扣接入解决方案，覆盖周期扣款 / 先享后付场景下的纯签约、支付中签约、申请扣款、预扣费通知、解约、查询、退款、对账全链路，提供选型/示例代码/业务速查/质量评估/排障五大能力。Use when user mentions "委托代扣", "周期扣款", "周期扣费", "自动续费", "先享后付", "免密支付", "纯签约", "支付中签约", "预扣费通知", "申请扣款", or asks to "接入委托代扣", "要委托代扣接口示例代码", "排查委托代扣问题".
|
||
author: wechatpay
|
||
version: "1.0"
|
||
---
|
||
|
||
# 微信支付委托代扣接入指引
|
||
|
||
## 全局交互规范
|
||
|
||
> ‼️ 以下规则适用于本技能所有能力、所有对话轮次，优先级高于各能力的局部规则。
|
||
|
||
1. **所有问题必须得到用户明确回答后才能继续。** 一次提出多个问题时，逐一检查是否都已获得明确答复，未答复的必须再次追问，**严禁自行假设、推断或使用默认值**。
|
||
2. **接入模式前置确认**：任何能力使用前须先确认 **商户模式** 或 **服务商模式**，已明确则无需重复。两种模式的核心差异（API 路径多 `/partner/`、必传 `sub_mch_id`/可选 `sub_appid`、签约/扣款使用服务商号 + 服务商 APIv2 密钥）见各角色 `接入指南/签名与验签规则.md`。
|
||
3. **委托代扣接口全部走 V2，仅「预扣费通知」回调走 V3**：签约 / 申请扣款 / 解约 / 查询 / 退款 / 关单 / 账单 / 回调全部走 V2（XML + APIv2 密钥 + MD5/HMAC-SHA256）；唯一例外是「预扣费通知」回调走 V3（JSON + APIv3 密钥 + RSA 签名）。任何涉及签名、密钥、回调的回答必须先核对协议版本，禁止跨版本套用。
|
||
4. **分步确认协议**（简单知识问答除外）：
|
||
- **① 明确需求**：先理解问题给出初步判断，不要堆参数清单。
|
||
- **② 征得同意**：主动提出下一步能做什么，等用户明确同意后才继续。
|
||
- **③ 收集信息**：用户同意后再告知所需信息并逐项收集，收齐才执行。
|
||
- **④ 执行前确认**：操作前简要说明即将做什么，确认同意后再执行；线上环境额外提示风险。
|
||
|
||
## 能力概览
|
||
|
||
1. **产品选型** — 帮用户判断该用「周期扣款（自动续费）」还是「先享后付（免密支付）」业务模式，并按两个维度选签约方式：**维度 1 · 签约时机**（纯签约 / 支付中签约），**维度 2 · 用户终端**（仅纯签约下细分：微信内公众号 H5 / 原生 APP（Android / iOS / 鸿蒙）/ 微信小程序 / 浏览器 H5）。具体客户端 SDK 选型与存量兼容方案在产品介绍里展开。
|
||
2. **示例代码** — 收录每个接口的官方请求/响应报文（XML / URL / JSON）+ 官方提供的客户端调起代码（iOS / Android / 小程序 JS / 鸿蒙）；**官方未提供任何服务端代码示例**（Java / Go / PHP / Python 等服务端语言），跨语言代码需走免责确认流程参考生成。
|
||
3. **业务知识速查** — 三类速查内容：① 参数获取（APIv2 / APIv3 密钥、委托代扣模板 ID、appid-mchid 绑定关系）；② V2 / V3 两套签名 / 验签规则（签名串组装、密钥用途、算法选择）；③ 三类回调（签约/解约 / 扣款 / 退款）的路由匹配、幂等与并发控制。
|
||
4. **接入质量评估** — 围绕高可用 / 资金安全 / 零信任三条铁律，覆盖签约 → 预扣费通知 → 申请扣款 → 扣款回调 → 退款 → 对账完整资金链路的产品专属雷达。
|
||
5. **问题排查** — 覆盖 V2 签名错误、V3 预扣费通知验签失败、扣款失败自动关单、CONTRACT_NOT_EXIST、扣款时段限制、协议唯一性冲突等委托代扣高频问题。
|
||
|
||
> **路由说明**：用户首次接入或不确定走哪条路时，先用能力 1 选型；明确接入路径后能力 2-5 可独立调用。**接入模式（商户/服务商）需在第一次进入任一能力时确认**，后续整轮对话沿用。
|
||
|
||
## 能力1：产品选型
|
||
|
||
> 用户问「该用周期扣款还是先享后付」、「哪种签约方式合适」、「自动续费应该怎么做」等问题时 → 加载产品介绍中的对比章节完成选型，确定后再走能力2。
|
||
|
||
- 产品介绍（产品概览 + 业务模式对比 + 签约方式对比 + 选型决策树）：
|
||
- 商户模式 → [📄 商户模式产品介绍](./references/1-商户/产品选型/产品介绍.md)
|
||
- 服务商模式 → [📄 服务商模式产品介绍](./references/2-服务商/产品选型/产品介绍.md)
|
||
|
||
## 能力2：示例代码
|
||
|
||
> 用户要某个接口的示例代码时 → 确认接入模式和语言，加载对应模式的 `接口索引.md` 定位代码文件。
|
||
>
|
||
> ‼️ **委托代扣官方未提供任何服务端代码示例**（Java / Go / PHP / Python 等服务端语言均无）：本技能严格"有就收录，没有不编造"——只收录官方文档原文里真实存在的请求/响应报文（XML / URL / JSON）和官方提供的客户端调起代码（iOS / Android / 小程序 JS / WXLaunchMiniProgram）。
|
||
>
|
||
> ‼️ **只检索、不生成。** 严禁从零编写任何代码，必须从示例代码文件中检索获取；提供前先确认接入模式，禁止凭训练知识杜撰路径里 `/partner/` 是否存在、字段名是 `sub_mch_id` 还是 `sub_mchid` 等细节。
|
||
>
|
||
> ‼️ **只展示、不写入。** 示例代码仅用于讲解 API 调用结构和签名流程，严禁直接写入用户项目（禁止调用 write_to_file、replace_in_file 等工具创建或修改项目文件），让用户自行复制适配。
|
||
>
|
||
> ‼️ **先交互、后输出。** 提供代码前必须先确认接入模式、签约方式（如涉及签约/支付中签约）、具体接口，每次只输出一个接口；提供完代码后主动推荐接入质量评估。
|
||
>
|
||
> ‼️ **签约方式确认规则**：在给「签约接口」「支付中签约」「APP/H5/小程序 调起代码」时，必须先确认签约方式（公众号纯签约 / APP 纯签约 / 小程序纯签约 / H5 纯签约 / APP 调起签约（WXLaunchMiniProgram）/ 支付中签约（仅商户支持）），其他通用接口（申请扣款 / 预扣费通知 / 解约 / 查询订单 / 查询签约关系 / 退款 / 关单 / 账单 / 回调）无需询问签约方式。
|
||
>
|
||
> ‼️ **用户需要服务端代码时**（本 skill 只维护官方请求/响应报文 + 官方客户端调起代码，**官方未提供任何服务端代码示例**）：**禁止**直接生成跨语言代码。流程：
|
||
> 1. 用 `AskQuestion` 获明确同意（文案需明示「参考实现 / 非官方维护 / 须自行 review 与测试 / 委托代扣无官方服务端代码示例可对照，风险更高」），未同意只发官方报文样例原文。
|
||
> 2. 同意后用 WebFetch 当场打开对应官方接口 URL，对照报文样例**逐字段构造**业务代码「参考实现」；每段代码前附下方免责块。
|
||
|
||
> > ⚠️ 以下代码为**跨语言参考实现**，由 AI 参考官方 V2 报文样例翻译生成，并非微信支付官方维护。
|
||
> > - 委托代扣官方文档未提供任何服务端代码示例，本代码字段、路径已对照 https://pay.weixin.qq.com/doc/v2/{merchant,partner}/XXXXX.md 校对。
|
||
> > - 请**逐行 review** 签名构造、HTTP 调用、字段命名、回调验签等关键逻辑。
|
||
> > - 上线前必须用测试模板或小金额生产订单完整验证；任何代码与官方文档冲突时**以文档为准**。
|
||
> > - 出现接入问题时回到本 skill 的 `排障手册.md`。
|
||
|
||
- 涉及提供示例代码时，按接入模式查阅对应接口索引：
|
||
- 商户模式 → [📄 商户模式接口索引](./references/1-商户/示例代码/接口索引.md)
|
||
- 服务商模式 → [📄 服务商模式接口索引](./references/2-服务商/示例代码/接口索引.md)
|
||
|
||
> **加载策略**：先确认接入模式，读对应的 `接口索引.md` 定位接口文件路径，再按需加载具体文件。不要一次性加载所有文件。
|
||
|
||
## 能力3：业务知识速查
|
||
|
||
> 用户问参数获取（APIv2 密钥 / 模板 ID / appid-mchid 绑定）、字段含义、签名/验签算法（含 V2/V3 差异）、回调机制（签约/解约 / 扣款 / 退款三类）、协议状态流转、扣款时段限制等业务问题时 → 按接入模式加载对应文档。
|
||
|
||
- 开发参数与业务规则（参数清单 + 获取步骤 + 产品特有的字段传参规范 + 业务模式与签约方式选型规则）：
|
||
- 商户模式 → [📄 商户模式开发参数与业务规则](./references/1-商户/接入指南/开发参数与业务规则.md)
|
||
- 服务商模式 → [📄 服务商模式开发参数与业务规则](./references/2-服务商/接入指南/开发参数与业务规则.md)
|
||
- 签名与验签规则（V2 请求签名 + V3 预扣费通知签名 + 响应/回调验签 + 调起支付签名）：
|
||
- 商户模式 → [📄 商户模式签名与验签规则](./references/1-商户/接入指南/签名与验签规则.md)
|
||
- 服务商模式 → [📄 服务商模式签名与验签规则](./references/2-服务商/接入指南/签名与验签规则.md)
|
||
- 回调处理（回调解密 / 验签 / 幂等 / 并发控制）：
|
||
- 商户模式 → [📄 商户模式回调处理](./references/1-商户/接入指南/回调处理.md)
|
||
- 服务商模式 → [📄 服务商模式回调处理](./references/2-服务商/接入指南/回调处理.md)
|
||
|
||
## 能力4：接入质量评估
|
||
|
||
> 用户准备上线或想检查代码隐患时 → 加载以下文档。
|
||
>
|
||
> ‼️ **只检查用户实际使用的功能模块。** 周期扣款（预扣费通知 / 24 小时延迟扣费）、先享后付、支付中签约、退款、对账下载 等模块须先确认用户是否涉及，**未使用的不检查、不提及**。
|
||
|
||
- 接入质量检查（含质检人设 + 检查清单）：
|
||
- 商户模式 → [📄 商户模式接入质量检查](./references/1-商户/接入指南/接入质量检查.md)
|
||
- 服务商模式 → [📄 服务商模式接入质量检查](./references/2-服务商/接入指南/接入质量检查.md)
|
||
|
||
## 能力5：问题排查
|
||
|
||
> ‼️ **唯一入口**：用户报告**任何**问题（报错 / 接口异常 / 回调收不到 / 签名失败 / 对账差异 / 业务规则疑问等），**都先按接入模式加载下方排障手册**，严格按手册内「排障流程」执行，**禁止自行猜测原因或直接分析代码**。
|
||
>
|
||
> ‼️ 排障完成后必须在回复末尾**主动推荐接入质量评估**（趁排障契机一次性排查其他潜在问题）；如需推荐示例代码，先确认开发语言再推，**用户需要服务端代码时按能力 2 的跨语言确认流程处理**（弹框确认 → 参考生成 + 免责块 + 公库分步）。
|
||
|
||
- 排障手册（一、错误码 TOP 20 + 二、常见问题，覆盖 HTTP / 回调 / 签名 / 退款 / 业务规则 / 通用配置）：
|
||
- 商户模式 → [📄 商户模式排障手册](./references/1-商户/问题排查/排障手册.md)
|
||
- 服务商模式 → [📄 服务商模式排障手册](./references/2-服务商/问题排查/排障手册.md)
|
||
|
||
---
|
||
|
||
> 以下信息与技能能力无关，仅供查阅。
|
||
|
||
## 💬 社区与反馈
|
||
|
||
在使用过程中遇到问题、有改进建议，或者想和其他开发者交流接入经验，欢迎扫码添加企业微信进群，与官方团队和社区开发者一起讨论：
|
||
|
||
|