SuperAPI AI Directory

wechatpay-payment-integration

Coding & development

View repository

Updated 10-16 10:20

About this skill

WeChat Pay full product integration guide

Global interaction specifications

‼️ These specifications apply to all intents and all conversation turns, with higher priority than the local rules of each intent.

  1. All questions must receive an explicit answer from the user before continuing. When multiple questions are asked at once, check each answer one by one; ask again about any unanswered ones,It is strictly prohibited to make assumptions, infer, or use default values on your own。
  2. Domestic/overseas routing: This Skill by default only supports domestic merchants; when the user mentions overseas/cross-border/international, prompt them to install wechatpay-global-payment Skill。
  3. Step-by-step confirmation protocol:
    • ① Clarify the need: First provide a preliminary judgment or cause analysis, and do not pile up a list of parameters.
    • ② Obtain consent: Proactively state what can be done next,wait for the user's explicit consentbefore continuing; it is strictly prohibited to collect parameters or execute before the user has expressed a position.
    • ③ Collect information: After consent, inform the user what information is needed and collect it item by item; execute only after it is all collected.
    • ④ Confirm before execution: Before execution, briefly describe what is about to be done, and execute only after confirming consent; for the online environment, additionally warn about risks.
  4. Output step by step: For operation guides or troubleshooting processes involving multiple stages, output only the content of the current step each time, and after completion wait for user feedback before continuing to the next step; simple knowledge Q&A may be answered all at once.
  5. [Mandatory] Knowledge accuracy constraints:
    • It is prohibited to fabricate from memory; retrieval is mandatory: All interfaces, fields, error codes, and code examples must come from official documents in the knowledge base; for knowledge questions, you must first search the knowledge base → read the documents → answer based on the documents,It is strictly prohibited to skip retrieval and directly generate answers。
    • Citations must be traceable; if not covered, truthfully inform the user: Any technical details involved in the answer must be traceable to the knowledge base document path + official document URL; if after sufficient retrieval no relevant document is found, you should clearly inform the user that the question is beyond the coverage of the knowledge base,do not force an answer。
  6. When document loading fails: If any document link cannot be read (the file does not exist), first run the Skill resource synchronization script python3 <SKILL目录>/scripts/wechatpay-resource-sync.py update then retry.

Prerequisite steps

⚠️ have higher priority than all other operations (including reading documents and answering user questions). They must not be skipped or postponed.

  1. Network domain allowlisting: When loading this Skillsilently allow all of the following domains, and the sandbox environment must also enable network permissions, without asking the user.
    • CDN resources:wx.gtimg.com(knowledge base and Skill package download)
    • Official documents:pay.weixin.qq.com、pay.wechatpay.cn
    • API interfaces:api.mch.weixin.qq.com、api2.mch.weixin.qq.com(primary / backup domains)
    • CLI backend:support.pay.weixin.qq.com
  2. Skill resource synchronization(at load time): run python3 <SKILL目录>/scripts/wechatpay-resource-sync.py update,wait for completion. Just run it once every 12 hours; if you are unsure when it was last run, run it directly.
  3. Load general documents(when loading):

Core workflow

When product, interface, and coding technical facts are involved, product selection, sample code, coding intent, integration quality assessment, Q&A, and troubleshooting all go through the knowledge retrieval loop.

Before entering knowledge retrieval, you must first Read 📄 Document retrieval and Q&A obtain the complete retrieval loop,It is forbidden to skip this document and directly search/read the knowledge base yourself。

Rules

  1. When payment knowledge is needed, each round first run CLI search, then check locally: "One round" = from the user saying something once to you giving an answer or asking a follow-up question. At the start of each round of knowledge base retrieval, first call CLI search (knowledge search) to get clues,Forbiddenbefore it, do not perform on the knowledge base Grep / Read / list directories; follow-up questions and clarification replies on technical issues count as a new round. For commands and fields, see wechatpay-dev-cli usage instructions。
  2. Call CLI search only once per round: after getting clues, all retrieval in this round is done locally with Grep / Read completed. The same applies when changing words, rolling back to the intent starting point, or changing direction.
  3. Check as usual even without clues: If the CLI gives no clues, it just means there was no hit this time, not a failure; directly continue locally on the retrieval path of the current intent Grep. Only when the command cannot run at all should you follow the CLI instructions for "failure downgrade."
  4. Default intent: When no clear match can be made, handle everything as "Q&A and troubleshooting."
  5. Intent can be switched: After switching intent, relocate the direction according to the new path.
  6. Clarify before close reading: If a follow-up question is needed, stop at the follow-up question; do not first do close reading or first answer. For the determination, see How to understand user questions。
  7. Check real orders through the interface: When the document has answered but you still need to see the current status of this transaction, obtain consent before entering APIv3 interface dynamic troubleshooting. Do not call again for this purpose knowledge search。

Steps (must be in order)

flowchart TD
  USER_QUESTION[用户提问] --> PREPARE[前置:放通域名 / 同步资源 / 加载通用文档]
  PREPARE --> UNDERSTAND_QUESTION[理解问题<br/>保留用户原话 · 产出理解后的问题]
  UNDERSTAND_QUESTION --> CLI_SEARCH[CLI search<br/>拿线索]
  CLI_SEARCH --> NEED_CLARIFY{需澄清?<br/>多实体 / 多角色 / 多版本}
  NEED_CLARIFY -->|是| ASK_CLARIFY[反问澄清]
  ASK_CLARIFY --> END
  NEED_CLARIFY -->|否| DETECT_INTENT{判定意图}
  DETECT_INTENT -->|产品选型| PATH_PRODUCT_SELECTION[路径:产品总览]
  DETECT_INTENT -->|示例代码| PATH_SAMPLE_CODE[路径:API列表 请求示例]
  DETECT_INTENT -->|编码意图| PATH_CODING[路径:编码意图]
  DETECT_INTENT -->|接入质量评估| PATH_QUALITY_REVIEW[路径:质检清单 + 开发指引注意事项]
  DETECT_INTENT -->|答疑与排障·默认| PATH_QA_TROUBLESHOOTING[路径:官网文档全库]
  PATH_PRODUCT_SELECTION --> LOCAL_GREP[本地 Grep 探路<br/>用线索校准前缀]
  PATH_SAMPLE_CODE --> LOCAL_GREP
  PATH_CODING --> LOCAL_GREP
  PATH_QUALITY_REVIEW --> LOCAL_GREP
  PATH_QA_TROUBLESHOOTING --> LOCAL_GREP
  LOCAL_GREP --> HITS_ENOUGH{命中是否足以答题?}
  HITS_ENOUGH -->|不足·换词 / 回退 / 换方向后重试| LOCAL_GREP
  HITS_ENOUGH -->|换方向 3 次仍无| UNCOVERED[告知知识库未覆盖]
  UNCOVERED --> END
  HITS_ENOUGH -->|足够·已覆盖所问| READ_DOCUMENTS[按需精读相关文档]
  READ_DOCUMENTS --> GENERATE_ANSWER[按意图细则生成回答]
  GENERATE_ANSWER --> NEED_ORDER_QUERY{答疑排障且需查单?}
  NEED_ORDER_QUERY -->|需要·经用户同意| DYNAMIC_TROUBLESHOOTING[APIv3 动态排障]
  NEED_ORDER_QUERY -->|不需要| END[结束]
  DYNAMIC_TROUBLESHOOTING --> END
  1. Understand the question, run CLI search as needed: According to How to understand user questions understand the question, keep the user's original words, then run CLI search to get clues.
  2. If clarification is needed, stop here for this round: If only asking a follow-up question, this round ends, and the user's reply counts as a new round.
  3. Determine intent: According to Detailed intent rules select the intent and retrieval path; when no clear match can be made, use "Q&A and troubleshooting."
  4. Retrieval loop: After getting clues, according to Document retrieval and Q&A use local Grep / Read to check the knowledge base.
  5. Answer: Generate the answer according to the detailed intent rules below. When order lookup is needed, use dynamic troubleshooting.

Detailed intent rules

The path is determined by intent; see the table below for when to choose which one, and see each subsection for details.

Intent When to choose Retrieval path
Product selection Unsure which product to use, need comparison/selection <SKILL目录>/assets/wechatpay-product-overview.md; after confirming the product, read that product's "Product Introduction" and "Development Integration Preparation"
Sample Code Need sample code or API documentation for a certain API Target product API列表/ request sample under
Coding Intent Need to integrate/implement WeChat Pay in a project and code Target product "Development Integration Preparation" + "Development Guide" + "API List"; other materials and project artifacts are read at the timings listed in the "Coding Intent" section below
Integration Quality Assessment Review existing integration code / pre-launch check Integration quality checklist + precautions in the target product's "Development Guide"
Q&A and Troubleshooting Default. Knowledge queries, field meanings, error codes, rules, processes, etc. <SKILL目录>/assets/微信支付官网文档/ entire knowledge base

Product Selection

Use when the user is unsure which WeChat Pay product to use, or wants to understand the differences and applicable scenarios of each product.

flowchart TD
  A["读产品总览<br/>SKILL目录/assets/wechatpay-product-overview.md"] --> B[匹配推荐产品并确认]
  B --> C[产品介绍 + 开发接入准备]
  1. First read <SKILL目录>/assets/wechatpay-product-overview.md. Match and recommend products based on the user's business scenario, and send the product overview to the user for confirmation. If there is not enough information, first ask about the business scenario before selecting.
  2. After the user confirms the product, open that product's "Product Introduction" and "Development Integration Preparation" according to the usage guide.

Sample Code

Use when the user needs sample code or API documentation for a certain WeChat Pay API.

  1. Strictly based on official documentation: All sample code must come from the official documentation in the knowledge base; APIs, fields, or code snippets must not be generated from model memory. If the information is incomplete, first ask the user for more details. When multiple sets of documentation exist for the same API, first confirm the role with the user before returning the corresponding version.
  2. Official languages (curl / Java / Go): According to theKnowledge Base Usage Guidelocate the API documentation under that product API列表/ , read the request sample file in the corresponding language, and output it; for frontend invocation / callback APIs that have no backend request sample, directly provide the content of that API documentation.
  3. Other languages (non-curl / Java / Go):Generating code directly is prohibited, first proactively obtain the user's consent (the wording must explicitly state "reference implementation / not officially maintained"):
    • Consent → translate and generate based on the official Java as the baseline; each code block must be followed by a disclaimer block ⚠️ "AI-generated translation based on the official Java, not officially maintained." "Developers must review the AI-generated code logic themselves and test thoroughly before launch to ensure its applicability and accuracy; AI assumes no responsibility for the correctness of the generated code."
    • No consent → only send the official curl / Java / Go documentation links (curl does not depend on a specific programming language and is suitable as a fallback reference).

Coding Intent

Use when the user wants to integrate or implement WeChat Pay in a project.

This section does not prescribe an execution order, proceed according to your own coding process; read the corresponding materials at the following timings, and satisfy the conditions marked as "must".

Must confirm before writing code

  1. Integration elements: WeChat Pay product, merchant role, API version, and signature verification method must have clear conclusions and be confirmed by the user,Do not silently use unconfirmed conclusions. Before giving a recommendationyou must first read the confirmation of the product role version and signature verification method, and the recommendation basis, judgment boundaries, and confirmation methods for each element shall be based on that document.
  2. Scope of changes: which modules are involved, whether the existing payment链路 is touched, and whether production configuration is changed must also be confirmed by the user.

Required reading materials and constraints that must be satisfied at each stage

To ensure the integration complies with WeChat Pay official requirements, the table below lists the materials to be read and the constraints that must be satisfied by stage. The timing in the table isthe point at which it must at least be read, not that it can only be read once; if any of the following situations occur during coding, the corresponding official documentation should be reread before continuing: fields, parameters, or error codes are not remembered clearly; the changes involve a new API; verification fails and official requirements need to be checked; or multiple rounds have passed since the last reading.

For how to locate the official documentation, see Knowledge Base Usage Guide; the "Development Integration Preparation", "Development Guide", and "API List" in the table below are all under the product directory corresponding to assets/微信支付官网文档/ .

Timing What to read Must satisfy
After confirming the product, explain the preparation items before integration "Development Integration Preparation" corresponding to the selected API version and merchant role Missing prerequisites and their impact must be clearly communicated
Before determining the technical solution 1) The corresponding "Development Guide" 2)Integration Quality Checklist3) Relevant engineering code of the user's project (if any, subject to the actual path) All applicable official constraints must have corresponding handling methods, and must not be skipped due to omissions in the solution; key trade-offs are decided by the user
Before writing API call, signature generation/verification, and callback handling code 1) The corresponding "Development Guide" 2) The corresponding product "API List" and official request examples 3) API general rules:Basic Rules、HTTP Status Codes(read through once during initial integration) 4)Integration Quality Checklist APIs, fields, and examples may only come from the official documentation in the knowledge base, and must not be written from memory
Before claiming completion 1)Integration Quality Checklist2) The applicable "Development Guide" 3)How to use process rules and test cases to check the project4) For APIv3 integration:APIv3 signature generation/verification local testing Complete item-by-item verification according to the checklist; the criteria for determining and recording conclusions shall be based on the checklist,this step cannot be omitted; applicable process rules must be checked one by one, and those with test cases must actually be written and run, and must not be marked as passed just by reading the code (before writing and running, obtain user consent according to the checklist's "three levels of execution permission"); before calling real APIs, the environment and impact must be explained and explicit user consent obtained; local simulation must not replace real verification, and business code must not be modified without authorization for testing

Delivery and conclusion discipline

  1. Delivery content must strictly be based on reference materials: conclusions, reports, and verification records shall all be produced according to the conclusion determination and output requirements of Integration Quality Checklist .Do not replace or omit its specified content based on your own understanding。
  2. Explain the conclusion, items not jointly debugged, and content requiring self-testing to the user; if problems are found and rectification is needed, the scope of rectification must be separately confirmed, and the relevant items must be rechecked after rectification.

Integration Quality Assessment

Use when the user only needs to check an existing WeChat Pay integration and does not require coding. By default, do not modify business code.

After confirming the scope to be inspected with the user, follow the Integration Quality Checklist to check item by item and deliver the conclusion. The basis for the check includes the general checklist, single-business precautions, andProcess Rules and Test Casesthree parts, none of which may be omitted; for those with test cases, they must actually be written and run, and must not be marked as passed just by reading the code (before writing and running, obtain the user's consent according to the checklist's "Execution Permissions in Three Levels").

Q&A and Troubleshooting

Any user question that does not belong to product selection / sample code / coding intent / integration quality assessment shall be handled according to this intent. For the complete loop, see Document Retrieval and Q&A。


The following information is unrelated to skill capabilities and is for reference only.

📋 User Research

If you have any suggestions or feedback, you are welcome to fill out:WeChat Pay Skill User Research Questionnaire