wechatpay-deduction-service

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

微信支付委托代扣接入指引

WeChat Pay Entrusted Withholding Access Guide

全局交互规范

Global Interaction Specifications

‼️ 以下规则适用于本技能所有能力、所有对话轮次,优先级高于各能力的局部规则。
  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. 分步确认协议(简单知识问答除外):
    • ① 明确需求:先理解问题给出初步判断,不要堆参数清单。
    • ② 征得同意:主动提出下一步能做什么,等用户明确同意后才继续。
    • ③ 收集信息:用户同意后再告知所需信息并逐项收集,收齐才执行。
    • ④ 执行前确认:操作前简要说明即将做什么,确认同意后再执行;线上环境额外提示风险。
‼️ The following rules apply to all capabilities and all conversation rounds of this skill, with higher priority than the local rules of each capability.
  1. All questions must receive clear answers from the user before proceeding. When multiple questions are raised at once, check one by one whether all have received clear responses. Unanswered questions must be followed up again, strictly prohibit making assumptions, inferences, or using default values.
  2. Pre-confirmation of Access Mode: Before using any capability, confirm the Merchant Mode or Service Provider Mode. If it has been clarified, there is no need to repeat. The core differences between the two modes (API path has an extra
    /partner/
    , mandatory
    sub_mch_id
    /optional
    sub_appid
    , signing/deduction use service provider account + service provider APIv2 key) can be found in
    Access Guide/Signature and Verification Rules.md
    for each role.
  3. All Entrusted Withholding interfaces use V2, only the "Pre-deduction Notification" callback uses V3: Signing / deduction application / contract termination / query / refund / order closing / bill / callback all use V2 (XML + APIv2 key + MD5/HMAC-SHA256); the only exception is the "Pre-deduction Notification" callback which uses V3 (JSON + APIv3 key + RSA signature). Any answer involving signatures, keys, or callbacks must first check the protocol version, and prohibit cross-version application.
  4. Step-by-step protocol confirmation (except for simple knowledge Q&A):
    • ① Clarify requirements: First understand the problem and give an initial judgment, do not pile up parameter lists.
    • ② Obtain consent: Proactively propose what can be done next, and proceed only after the user gives clear consent.
    • ③ Collect information: After the user agrees, inform the required information and collect it item by item, and proceed only after all information is collected.
    • ④ Confirm before execution: Briefly explain what will be done before the operation, and execute only after confirming consent; additionally prompt risks for online environments.

能力概览

Capability Overview

  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. Product Selection — Help users determine whether to use the "Periodic Deduction (Auto-renewal)" or "Postpaid Service with Upfront Benefits (Password-free Payment)" business mode, and select the signing method according to two dimensions: Dimension 1 · Signing Timing (pure signing / signing during payment), Dimension 2 · User Terminal (only subdivided under pure signing: WeChat Official Account H5 / Native APP (Android / iOS / HarmonyOS) / WeChat Mini Program / Browser H5). Specific client SDK selection and stock compatibility solutions are expanded in the product introduction.
  2. Sample Code — Collect official request/response messages (XML / URL / JSON) for each interface + official client invocation code (iOS / Android / Mini Program JS / HarmonyOS); the official does not provide any server-side code samples (Java / Go / PHP / Python and other server-side languages). Cross-language code needs to go through the disclaimer confirmation process for reference generation.
  3. Business Quick Reference — Three types of quick reference content: ① Parameter acquisition (APIv2 / APIv3 key, Entrusted Withholding template ID, appid-mchid binding relationship); ② V2 / V3 signature/verification rules (signature string assembly, key usage, algorithm selection); ③ Route matching, idempotency and concurrency control for three types of callbacks (signing/contract termination / deduction / refund).
  4. Access Quality Assessment — Focusing on the three iron rules of high availability / fund security / zero trust, covering the exclusive product radar for the complete fund link from signing → pre-deduction notification → deduction application → deduction callback → refund → reconciliation.
  5. Troubleshooting — Covers high-frequency Entrusted Withholding issues such as V2 signature errors, V3 pre-deduction notification verification failures, automatic order closing due to deduction failures, CONTRACT_NOT_EXIST, deduction time restrictions, protocol uniqueness conflicts, etc.
Routing Instructions: When a user accesses for the first time or is unsure which path to take, use Capability 1 for selection first; after clarifying the access path, Capabilities 2-5 can be called independently. The access mode (Merchant/Service Provider) must be confirmed when entering any capability for the first time, and will be used for the entire subsequent conversation round.

能力1:产品选型

Capability 1: Product Selection

用户问「该用周期扣款还是先享后付」、「哪种签约方式合适」、「自动续费应该怎么做」等问题时 → 加载产品介绍中的对比章节完成选型,确定后再走能力2。
  • 产品介绍(产品概览 + 业务模式对比 + 签约方式对比 + 选型决策树):
    • 商户模式 → 📄 商户模式产品介绍
    • 服务商模式 → 📄 服务商模式产品介绍
When users ask questions like "Should I use periodic deduction or postpaid service with upfront benefits", "Which signing method is suitable", "How to implement auto-renewal", etc. → Load the comparison chapter in the product introduction to complete the selection, then proceed to Capability 2.
  • Product Introduction (Product Overview + Business Mode Comparison + Signing Method Comparison + Selection Decision Tree):
    • Merchant Mode → 📄 Merchant Mode Product Introduction
    • Service Provider Mode → 📄 Service Provider Mode Product Introduction

能力2:示例代码

Capability 2: Sample Code

用户要某个接口的示例代码时 → 确认接入模式和语言,加载对应模式的
接口索引.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
  • 涉及提供示例代码时,按接入模式查阅对应接口索引:
    • 商户模式 → 📄 商户模式接口索引
    • 服务商模式 → 📄 服务商模式接口索引
加载策略:先确认接入模式,读对应的
接口索引.md
定位接口文件路径,再按需加载具体文件。不要一次性加载所有文件。
When users request sample code for a certain interface → Confirm the access mode and language, load the
Interface Index.md
of the corresponding mode to locate the code file.
‼️ The official does not provide any server-side code samples for Entrusted Withholding (no Java / Go / PHP / Python and other server-side languages are available): This skill strictly "collects what exists, does not fabricate what does not exist" — only collects the request/response messages (XML / URL / JSON) that actually exist in the official document and the official client invocation code (iOS / Android / Mini Program JS / WXLaunchMiniProgram).
‼️ Only retrieve, do not generate. Strictly prohibit writing any code from scratch, must retrieve and obtain from sample code files; confirm the access mode before providing, prohibit guessing details such as whether
/partner/
exists in the path, whether the field name is
sub_mch_id
or
sub_mchid
based on training knowledge.
‼️ Only display, do not write. Sample code is only used to explain API invocation structure and signature process, strictly prohibit directly writing into the user's project (prohibit using tools like write_to_file, replace_in_file to create or modify project files), let users copy and adapt by themselves.
‼️ Interact first, then output. Before providing code, must confirm the access mode, signing method (if involving signing/signing during payment), specific interface, and output only one interface each time; actively recommend access quality assessment after providing the code.
‼️ Signing Method Confirmation Rules: When providing "signing interface" "signing during payment" "APP/H5/Mini Program invocation code", must first confirm the signing method (Official Account pure signing / APP pure signing / Mini Program pure signing / H5 pure signing / APP-initiated signing (WXLaunchMiniProgram) / signing during payment (only supported by merchants)), no need to ask about the signing method for other general interfaces (deduction application / pre-deduction notification / contract termination / order query / signing relationship query / refund / order closing / bill / callback).
‼️ When users need server-side code (this skill only maintains official request/response messages + official client invocation code, the official does not provide any server-side code samples): Prohibit directly generating cross-language code. Process:
  1. Obtain clear consent using
    AskQuestion
    (the copy must clearly state "reference implementation / not officially maintained / must review and test by yourself / no official server-side code samples for Entrusted Withholding to compare, higher risk"), if not agreed, only send the original official message sample.
  2. After consent, use WebFetch to open the corresponding official interface URL on the spot, and construct the "reference implementation" of business code field by field according to the message sample; attach the following disclaimer block before each code segment.
⚠️ The following code is a cross-language reference implementation, generated by AI based on the official V2 message sample translation, and is not maintained by WeChat Pay official.
  • WeChat Pay official documentation does not provide any server-side code samples for Entrusted Withholding, the fields and paths of this code have been checked against https://pay.weixin.qq.com/doc/v2/{merchant,partner}/XXXXX.md.
  • Please review line by line key logics such as signature construction, HTTP invocation, field naming, callback verification.
  • Must fully verify with test templates or small-amount production orders before going online; follow the official documentation if any code conflicts with it.
  • Return to the
    Troubleshooting Manual.md
    of this skill when encountering access issues.
  • When providing sample code, refer to the corresponding interface index according to the access mode:
    • Merchant Mode → 📄 Merchant Mode Interface Index
    • Service Provider Mode → 📄 Service Provider Mode Interface Index
Loading Strategy: First confirm the access mode, read the corresponding
Interface Index.md
to locate the interface file path, then load the specific file as needed. Do not load all files at once.

能力3:业务知识速查

Capability 3: Business Quick Reference

用户问参数获取(APIv2 密钥 / 模板 ID / appid-mchid 绑定)、字段含义、签名/验签算法(含 V2/V3 差异)、回调机制(签约/解约 / 扣款 / 退款三类)、协议状态流转、扣款时段限制等业务问题时 → 按接入模式加载对应文档。
  • 开发参数与业务规则(参数清单 + 获取步骤 + 产品特有的字段传参规范 + 业务模式与签约方式选型规则):
    • 商户模式 → 📄 商户模式开发参数与业务规则
    • 服务商模式 → 📄 服务商模式开发参数与业务规则
  • 签名与验签规则(V2 请求签名 + V3 预扣费通知签名 + 响应/回调验签 + 调起支付签名):
    • 商户模式 → 📄 商户模式签名与验签规则
    • 服务商模式 → 📄 服务商模式签名与验签规则
  • 回调处理(回调解密 / 验签 / 幂等 / 并发控制):
    • 商户模式 → 📄 商户模式回调处理
    • 服务商模式 → 📄 服务商模式回调处理
When users ask business questions such as parameter acquisition (APIv2 key / template ID / appid-mchid binding), field meaning, signature/verification algorithm (including V2/V3 differences), callback mechanism (three types: signing/contract termination / deduction / refund), protocol status flow, deduction time restrictions, etc. → Load the corresponding document according to the access mode.
  • Development Parameters and Business Rules (parameter list + acquisition steps + product-specific field parameter transmission specifications + business mode and signing method selection rules):
    • Merchant Mode → 📄 Merchant Mode Development Parameters and Business Rules
    • Service Provider Mode → 📄 Service Provider Mode Development Parameters and Business Rules
  • Signature and Verification Rules (V2 request signature + V3 pre-deduction notification signature + response/callback verification + payment initiation signature):
    • Merchant Mode → 📄 Merchant Mode Signature and Verification Rules
    • Service Provider Mode → 📄 Service Provider Mode Signature and Verification Rules
  • Callback Processing (callback decryption / verification / idempotency / concurrency control):
    • Merchant Mode → 📄 Merchant Mode Callback Processing
    • Service Provider Mode → 📄 Service Provider Mode Callback Processing

能力4:接入质量评估

Capability 4: Access Quality Assessment

用户准备上线或想检查代码隐患时 → 加载以下文档。
‼️ 只检查用户实际使用的功能模块。 周期扣款(预扣费通知 / 24 小时延迟扣费)、先享后付、支付中签约、退款、对账下载 等模块须先确认用户是否涉及,未使用的不检查、不提及
  • 接入质量检查(含质检人设 + 检查清单):
    • 商户模式 → 📄 商户模式接入质量检查
    • 服务商模式 → 📄 服务商模式接入质量检查
When users are ready to go online or want to check code hidden dangers → Load the following documents.
‼️ Only check the functional modules actually used by the user. Modules such as periodic deduction (pre-deduction notification / 24-hour delayed deduction), postpaid service with upfront benefits, signing during payment, refund, reconciliation download must first confirm whether the user involves them, do not check or mention unused modules.
  • Access Quality Inspection (including quality inspection persona + inspection checklist):
    • Merchant Mode → 📄 Merchant Mode Access Quality Inspection
    • Service Provider Mode → 📄 Service Provider Mode Access Quality Inspection

能力5:问题排查

Capability 5: Troubleshooting

‼️ 唯一入口:用户报告任何问题(报错 / 接口异常 / 回调收不到 / 签名失败 / 对账差异 / 业务规则疑问等),都先按接入模式加载下方排障手册,严格按手册内「排障流程」执行,禁止自行猜测原因或直接分析代码
‼️ 排障完成后必须在回复末尾主动推荐接入质量评估(趁排障契机一次性排查其他潜在问题);如需推荐示例代码,先确认开发语言再推,用户需要服务端代码时按能力 2 的跨语言确认流程处理(弹框确认 → 参考生成 + 免责块 + 公库分步)。
  • 排障手册(一、错误码 TOP 20 + 二、常见问题,覆盖 HTTP / 回调 / 签名 / 退款 / 业务规则 / 通用配置):
    • 商户模式 → 📄 商户模式排障手册
    • 服务商模式 → 📄 服务商模式排障手册

以下信息与技能能力无关,仅供查阅。
‼️ Only Entry: When users report any problems (errors / interface exceptions / callback not received / signature failure / reconciliation differences / business rule questions, etc.), first load the troubleshooting manual below according to the access mode, strictly follow the "troubleshooting process" in the manual to execute, prohibit guessing the cause or directly analyzing the code by yourself.
‼️ After troubleshooting, must actively recommend access quality assessment at the end of the reply (take the opportunity of troubleshooting to check other potential problems at once); if you need to recommend sample code, confirm the development language first, when users need server-side code, follow the cross-language confirmation process of Capability 2 (pop-up confirmation → reference generation + disclaimer block + public library step-by-step).
  • Troubleshooting Manual (1. Top 20 Error Codes + 2. Common Problems, covering HTTP / callback / signature / refund / business rules / general configuration):
    • Merchant Mode → 📄 Merchant Mode Troubleshooting Manual
    • Service Provider Mode → 📄 Service Provider Mode Troubleshooting Manual

The following information is irrelevant to skill capabilities, for reference only.

💬 社区与反馈

💬 Community and Feedback

在使用过程中遇到问题、有改进建议,或者想和其他开发者交流接入经验,欢迎扫码添加企业微信进群,与官方团队和社区开发者一起讨论:
微信支付 Skills 交流群二维码
If you encounter problems during use, have improvement suggestions, or want to communicate access experience with other developers, welcome to scan the QR code to add the enterprise WeChat and join the group to discuss with the official team and community developers:
WeChat Pay Skills Communication Group QR Code