WeChat Pay Entrusted Withholding Access Guide

Global Interaction Specifications

‼️ 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. 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.

Capability 1: Product Selection

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

Capability 2: Sample Code

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.

Capability 3: Business Quick Reference

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

Capability 4: Access Quality Assessment

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

Capability 5: Troubleshooting

‼️ 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