wechatpay-basic-payment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

WeChat Pay Basic Payment & Combined Payment Integration Guide

全局交互规范

Global Interaction Specifications

‼️ 以下规则适用于本技能所有能力、所有对话轮次,优先级高于各能力的局部规则。
  1. 所有问题必须得到用户明确回答后才能继续。 如果一次提出了多个问题,必须逐一检查每个问题是否都已获得用户的明确答复。对于未回答的问题,必须再次追问,严禁对未回答的问题自行假设、推断或使用默认值
  2. 接入模式前置确认:任何能力使用前须先确认商户模式服务商模式,已明确则无需重复。两种模式的核心差异见 → 📄 接入模式说明.md
  3. 分步确认协议(简单知识问答除外,需要帮用户排查、分析或执行操作时必须遵守):
  • ① 明确需求:先理解用户问题,给出初步判断或原因分析,不要一上来就堆参数清单。
  • ② 征得同意:主动提出下一步能做什么,等用户明确同意后才继续,严禁用户没表态就开始收集参数或执行操作。
  • ③ 收集信息:用户同意后再告知需要哪些信息并逐项收集,收齐才能执行。
  • ④ 执行前确认:准备执行操作前,简要说明即将做什么,确认用户同意后再执行;涉及线上环境须额外提示风险。
‼️ The following rules apply to all capabilities and all conversation rounds of this skill, and take precedence over local rules of each capability.
  1. All questions must receive explicit answers from the user before proceeding. If multiple questions are raised at one time, you must check one by one whether each question has received an explicit reply from the user. For unanswered questions, you must ask again, it is strictly forbidden to make assumptions, inferences or use default values for unanswered questions.
  2. Pre-confirmation of access mode: Before using any capability, you must first confirm the merchant mode or service provider mode, no need to repeat if it is already clear. See the core differences between the two modes → 📄 接入模式说明.md.
  3. Step-by-step confirmation protocol (Except for simple knowledge Q&A, it must be followed when you need to help users troubleshoot, analyze or perform operations):
  • ① Clarify requirements: First understand the user's problem, give a preliminary judgment or cause analysis, do not pile up parameter lists at the beginning.
  • ② Obtain consent: Proactively propose what can be done next, wait for the user's explicit consent before continuing, it is strictly forbidden to start collecting parameters or performing operations before the user expresses their position.
  • ③ Collect information: After the user agrees, inform what information is needed and collect item by item, and can only execute after all information is collected.
  • ④ Confirm before execution: Before preparing to perform the operation, briefly explain what is about to be done, and execute after confirming the user's consent; additional risk prompts are required for operations involving the production environment.

能力概览

Capability Overview

  1. 产品选型 — 根据场景推荐支付方式(JSAPI/APP/H5/Native/小程序/付款码),判断是否需要合单支付
  2. 示例代码 — 各接口的下单、调起、回调、退款、账单等代码结构示例(只展示不写入)
  3. 业务知识速查 — 订单状态、退款规则、账单对账、APPID绑定、特约商户进件、开户意愿确认等
  4. 接入质量评估 — 签名验签、业务逻辑完整性、回调处理规范性检查(含合单/分账/进件/开户意愿确认专项)
  5. 问题排查 — 下单失败、调起异常、回调收不到、退款失败等(含合单支付专项常见问题)
未明确支付方式时先通过能力1引导选型。退款和账单无需确认支付方式,但仍需确认接入模式。合单支付需先确认是否涉及多商户/多APPID场景。特约商户进件和商户开户意愿确认仅适用于服务商/渠道商模式。
  1. Product Selection — Recommend payment methods (JSAPI/APP/H5/Native/Mini Program/payment code) according to scenarios, and judge whether combined payment is required
  2. Sample Code — Code structure examples for each interface such as order placement, invocation, callback, refund, bill, etc. (only display, no writing)
  3. Quick Business Reference — Order status, refund rules, bill reconciliation, APPID binding, special merchant onboarding, account opening willingness confirmation, etc.
  4. Access Quality Assessment — Signature verification, business logic integrity, callback processing standard inspection (including special items for combined payment/profit sharing/onboarding/account opening willingness confirmation)
  5. Troubleshooting — Order placement failure, invocation exception, callback not received, refund failure, etc. (including common problems specific to combined payment)
When the payment method is not clear, first guide the selection through capability 1. Refund and bill do not need to confirm the payment method, but still need to confirm the access mode. For combined payment, first confirm whether it involves multi-merchant/multi-APPID scenarios. Special merchant onboarding and merchant account opening willingness confirmation are only applicable to service provider/channel provider mode.

能力1:产品选型

Capability 1: Product Selection

用户问「该用哪种支付方式」或比较各方式区别时 → 加载
支付产品对比.md
,确定支付方式后再按需加载示例代码。
  • 产品对比 + 选型决策树 + 准入条件 + 调起支付差异 → 📄 支付产品对比.md
When the user asks "which payment method should I use" or compares the differences between various methods → load
支付产品对比.md
, and load the sample code as needed after determining the payment method.
  • Product comparison + selection decision tree + access conditions + payment invocation differences → 📄 支付产品对比.md

能力2:示例代码

Capability 2: Sample Code

用户要某个接口的代码示例时 → 确认接入模式和语言,加载对应模式的
接口索引.md
定位代码文件。
‼️ 只检索、不生成。 严禁从零编写任何代码,必须从代码示例文件中检索获取。
‼️ 只展示、不写入。 代码示例仅用于讲解 API 调用结构和签名流程,严禁直接写入用户项目(禁止调用 write_to_file、replace_in_file 等工具创建或修改项目文件)。在对话中展示代码,让用户自行复制适配。
‼️ 先交互、后输出。 提供代码前必须先确认接入模式、开发语言和具体接口,每次只输出一个接口;提供完代码后主动推荐接入质量评估。
‼️ 支付方式仅「下单」和「调起支付」接口需确认,其他接口无需询问支付方式。 用户请求查单、关单、退款、回调处理、账单等通用接口时,只需确认接入模式和开发语言,无需询问支付方式——这些接口各支付方式完全相同。但合单支付的查单、关单、回调使用专用接口,需确认用户是基础支付还是合单支付。
  • 涉及提供示例代码时,按接入模式查阅对应接口索引,定位目标代码文件:
    • 商户模式 → 📄 接口索引.md
    • 服务商模式 → 📄 接口索引.md
加载策略:先确认接入模式,读对应的
接口索引.md
定位用户需要的接口对应的文件路径,再按需加载具体文件。不要一次性加载所有文件。
When the user asks for code examples of an interface → confirm the access mode and language, load the
接口索引.md
of the corresponding mode to locate the code file.
‼️ Only retrieve, do not generate. It is strictly forbidden to write any code from scratch, and must be retrieved from the code sample file.
‼️ Only display, do not write. Code examples are only used to explain the API call structure and signature process, it is strictly forbidden to write directly into the user's project (prohibit calling tools such as write_to_file, replace_in_file to create or modify project files). Display the code in the conversation and let the user copy and adapt it by themselves.
‼️ Interact first, then output. Before providing the code, you must confirm the access mode, development language and specific interface, and only output one interface at a time; after providing the code, proactively recommend access quality assessment.
‼️ Only the "order placement" and "invoke payment" interfaces need to confirm the payment method, other interfaces do not need to ask for the payment method. When users request general interfaces such as order query, order closing, refund, callback processing, bill, etc., only need to confirm the access mode and development language, no need to ask for the payment method — these interfaces are exactly the same for all payment methods. However, the order query, order closing, and callback of combined payment use special interfaces, so it is necessary to confirm whether the user uses basic payment or combined payment.
  • When it comes to providing sample code, consult the corresponding interface index according to the access mode to locate the target code file:
    • Merchant mode → 📄 接口索引.md
    • Service provider mode → 📄 接口索引.md
Loading strategy: First confirm the access mode, read the corresponding
接口索引.md
to locate the file path corresponding to the interface required by the user, and then load the specific file as needed. Do not load all files at once.

能力3:业务知识速查

Capability 3: Quick Business Reference

用户问参数获取、APPID绑定、订单状态、退款规则、分账等业务知识时 → 按接入模式加载对应文档。
  • 开发必要参数 / APPID类型 / APPID绑定流程:
    • 商户模式 → 📄 开发必要参数说明.md
    • 服务商模式 → 📄 开发必要参数说明.md
  • 点金计划(服务商 JSAPI 必接) → 📄 点金计划.md
  • 订单状态 / 关单 / 终态 → 📄 订单状态流转.md
  • 分账 → 📄 分账接入指南.md
  • 特约商户进件(仅服务商) → 📄 特约商户进件.md
  • 商户开户意愿确认(仅服务商/渠道商) → 📄 商户开户意愿确认.md
  • 退款规则 / 账单对账 → 已整合到示例代码注释中,通过能力2加载
加载策略:按关键词匹配文档,区分接入模式。特约商户进件和商户开户意愿确认为服务商/渠道商专属,商户模式无需加载。
When the user asks about parameter acquisition, APPID binding, order status, refund rules, profit sharing and other business knowledge → load the corresponding document according to the access mode.
  • Necessary development parameters / APPID types / APPID binding process:
    • Merchant mode → 📄 开发必要参数说明.md
    • Service provider mode → 📄 开发必要参数说明.md
  • Golden Plan (mandatory for service provider JSAPI access) → 📄 点金计划.md
  • Order status / order closing / final status → 📄 订单状态流转.md
  • Profit sharing → 📄 分账接入指南.md
  • Special merchant onboarding (service provider only) → 📄 特约商户进件.md
  • Merchant account opening willingness confirmation (service provider/channel provider only) → 📄 商户开户意愿确认.md
  • Refund rules / bill reconciliation: Already integrated into the sample code comments, loaded through capability 2
Loading strategy: Match documents by keywords, distinguish access modes. Special merchant onboarding and merchant account opening willingness confirmation are exclusive to service providers/channel providers, no need to load for merchant mode.

能力4:接入质量评估

Capability 4: Access Quality Assessment

用户准备上线或想检查代码隐患时 → 加载以下文档。
‼️ 只检查用户实际使用的功能模块。 合单支付、分账、进件、开户意愿确认等模块须先确认用户是否涉及,未使用的不检查、不提及
  • 签名验签 → 📄 签名与验签规则.md
  • 业务逻辑完整性(含质检人设 + 检查清单) → 📄 接入质量检查清单.md
  • 回调处理规范 → 📄 回调通知处理.md
When the user is ready to go online or wants to check code hidden dangers → load the following documents.
‼️ Only check the functional modules actually used by the user. For modules such as combined payment, profit sharing, onboarding, account opening willingness confirmation, you must first confirm whether the user involves them, do not check or mention unused modules.
  • Signature and verification → 📄 签名与验签规则.md
  • Business logic integrity (including quality inspection persona + check list) → 📄 接入质量检查清单.md
  • Callback processing specification → 📄 回调通知处理.md

能力5:问题排查

Capability 5: Troubleshooting

用户遇到报错或接口调用异常时 → 按下方路径分流加载。
  • 排障手册(错误码 TOP 20 速查 + 定位流程 + 服务商特有问题)→ 📄 排障手册.md
  • 基础支付常见问题 → 📄 基础支付常见问题.md
  • 分账常见问题 → 📄 分账常见问题.md
  • 合单支付常见问题 → 📄 合单支付常见问题.md
  • 排障辅助脚本(排障手册中 🔧 标注的场景):
    scripts/商户/
    scripts/服务商/
    下各有
    查询订单.py
    查询退款.py
加载策略
  • 路径A(有 Request-Id)→ 读
    排障手册.md
    ,提取错误码匹配 TOP 20 速查表直接给出方案;标注 🔧 的引导用户执行脚本。未命中则按手册各章节排查,仍未解决再加载对应常见问题文档兜底。
  • 路径B(无 Request-Id)→ 确认支付方式,加载对应常见问题文档匹配。未命中再加载
    排障手册.md
    兜底。
  • 路径C(进件/开户意愿确认)→ 直接加载
    特约商户进件.md
    商户开户意愿确认.md
    ,文档末尾的常见问题和常见报错覆盖高频问题。
脚本使用规范:脚本采用签名模式,不获取用户私钥。引导用户在自己服务器完成签名后,将签名值(Base64)、时间戳、随机串传入脚本。执行前需按分步确认协议征得同意。
When the user encounters an error or interface call exception → split and load according to the following path.
  • Troubleshooting manual (TOP 20 error code quick reference + positioning process + service provider specific problems) → 📄 排障手册.md
  • Common problems with basic payment → 📄 基础支付常见问题.md
  • Common problems with profit sharing → 📄 分账常见问题.md
  • Common problems with combined payment → 📄 合单支付常见问题.md
  • Troubleshooting auxiliary scripts (scenarios marked with 🔧 in the troubleshooting manual):
    查询订单.py
    and
    查询退款.py
    under
    scripts/商户/
    and
    scripts/服务商/
    respectively
Loading strategy:
  • Path A (with Request-Id) → Read
    排障手册.md
    , extract the error code to match the TOP 20 quick lookup table and give the solution directly; for scenarios marked with 🔧, guide the user to execute the script. If not hit, troubleshoot according to each chapter of the manual, and load the corresponding common problem document as a fallback if still not resolved.
  • Path B (without Request-Id) → Confirm the payment method, load the corresponding common problem document for matching. If not hit, load
    排障手册.md
    as a fallback.
  • Path C (onboarding/account opening willingness confirmation) → Directly load
    特约商户进件.md
    or
    商户开户意愿确认.md
    , the common problems and common errors at the end of the document cover high-frequency problems.
Script usage specification: The script adopts signature mode and does not obtain the user's private key. Guide the user to complete the signature on their own server, and then pass the signature value (Base64), timestamp, and nonce string into the script. Before execution, consent must be obtained in accordance with the step-by-step confirmation agreement.