wechatpay-medical-insurance-payment

WeChat Pay medical insurance payment integration guide

Global interaction specifications

‼️ The following rules apply to all capabilities and all conversation turns of this skill, and take precedence over the local rules of each capability.

1. All questions must receive a clear answer from the user before continuing. When multiple questions are asked at once, check one by one whether each has received a clear answer, and any unanswered question must be asked again,It is strictly prohibited to make assumptions, infer, or use default values on your own。
2. Pre-confirmation of integration mode: Before using any capability, first confirm merchant mode or service provider mode, and if already clarified, there is no need to repeat. For the core differences between the two modes (parameter naming, API paths, signature utility classes), see each role's 接入指南/签名与验签规则.md。
3. Step-by-step confirmation protocol(except for simple knowledge Q&A):
   • ① Clarify requirements: First understand the question and give a preliminary judgment; do not pile up a list of parameters.
   • ② Obtain consent: Proactively propose what can be done next, and continue only after the user clearly agrees.
   • ③ Collect information: After the user agrees, inform them of the required information and collect it item by item; execute only after all is collected.
   • ④ Confirm before execution: Briefly explain what is about to be done before the operation, and execute only after confirmation and consent; additionally warn about risks for the production environment.

Capability overview

1. Product selection — Understand the functional positioning of Mobile Medical Insurance Payment 2.0, mixed payment types (pure self-pay / pure medical insurance / medical insurance and self-pay mixed), order types (registration / during consultation / inpatient / pharmacy / internet hospital, etc.), and integration prerequisites
2. Sample code — A full set of interfaces for mixed medical insurance and self-pay ordering, order query (mixed order number / merchant order number / practitioner institution order number), medical insurance refund notification, JSAPI / Mini Program invocation of mixed medical insurance and self-pay payment, and successful payment callback
3. Business knowledge quick reference — Development parameters and business rules (including medical insurance city ID, medical institution code, medical insurance electronic certificate authorization information, sensitive field encryption), mixed payment type determination, amount formulas, order status transitions, signature generation and verification, and callback handling
4. Integration quality assessment — General security radar + medical insurance payment dedicated radar: amount formula legality, public-key encryption of sensitive fields (name / ID card digest), three-choose-one constraint for medical insurance order fields, medical insurance refund notification idempotency, (service provider)sub_mchid routing anti-cross-order
5. Troubleshooting — Top 20 error codes + common issues, covering HTTP errors / callbacks not received / signature failure / amount verification failure / medical insurance bureau business errors / role-specific issues / general integration configuration

Routing instructions: Capability 1 is used for product conceptual questions and confirmation of integration prerequisites. Those who have already confirmed integration with medical insurance payment can skip directly to Capability 2/3. Capabilities 2 and 3 can be called independently, but the "integration mode prerequisite confirmation" must be completed first for the first time. After Capability 5 hits an error code or common issue, Capability 4 must be recommended at the end for a one-time self-check.

Capability 1: Product Selection

When the user asks "What is this product / What can it do / What scenarios is it suitable for / What prerequisites are needed for integration / How should merchants and service providers choose / What is the difference between direct connection and indirect connection" → load the product introduction document to answer. Those who have already confirmed integration with medical insurance payment can skip directly to Capability 2/3.

• Product introduction (product overview + use cases + integration prerequisites):
  • Merchant mode → 📄 Merchant Mode Product Introduction
  • Service provider mode → 📄 Service Provider Mode Product Introduction

Capability 2: Sample Code

When the user requests sample code for a certain API → confirm the integration mode and language, and load the corresponding mode's 接口索引.md to locate the code file.

‼️ Retrieve only, do not generate. Writing any code from scratch is strictly prohibited; it must be retrieved from the sample code files.

‼️ Display only, do not write. Sample code is only used to explain the API call structure and signing process. It is strictly prohibited to directly write it into the user's project (calling tools such as write_to_file, replace_in_file, etc. to create or modify project files is prohibited); let the user copy and adapt it themselves.

‼️ Interact first, output later. Before providing code, the integration mode, development language, and specific API must be confirmed first, and only one API should be output each time; after providing the code, proactively recommend integration quality assessment.

‼️ When the user's language is not Java/Go(this skill only maintains Java/Go examples):Prohibitedto directly generate cross-language code. Process:

1. Use AskQuestion to obtain explicit consent (the wording must clearly state "reference implementation / not officially maintained / must be reviewed and tested by yourself"); if consent is not given, only send the official Java/Go original text.

2. After consent, use the official Java example as the baseline to translate and generate business code "reference implementation"; then use plain text to ask whether to translate the Java public libraries (SDK utility classes + HTTP client); if not explicitly requested, do not include them. Attach the disclaimer block below before each code segment.

⚠️ The following code is across-language reference implementation, generated by AI translating with reference to the official Java example, and is not officially maintained by WeChat Pay.

• Pleasereview line by line key logic such as signature construction, HTTP calls, field naming, and callback decryption.
• Before launch, it must be fully verified in the test environment. It is recommended to first use the official Java/Go examples to get the main flow working as a comparison.
• If integration issues occur, the official Java/Go examples shall prevail.

‼️ Rules for confirming the launch client type: "Invoking medical insurance self-pay mixed payment" must first confirm the launch client type (JSAPI Official Account H5 / Mini Program); different clients have different message and signature rules; other general APIs (order placement / order query / medical insurance refund notification / payment success callback) do not require asking about the launch client.

• When sample code is to be provided, consult the corresponding API index according to the integration mode:
  • Merchant mode → 📄 Merchant Mode API Index
  • Service provider mode → 📄 Service Provider Mode API Index

Loading Strategy: First confirm the integration mode, read the corresponding 接口索引.md to locate the API file path, then load specific files as needed. Do not load all files at once.

Capability 3: Business Knowledge Quick Reference

When the user asks about development parameters and business rules (mchid / sub_mchid / appid / sub_appid / APIv3 key / merchant API certificate / WeChat Pay public key / city ID / medical institution code / medical insurance electronic credential authorization information), hybrid payment type determination, amount formulas, order status transitions, sensitive field encryption, signature rules, callback mechanisms, and other business knowledge → load the corresponding documents according to the integration mode.

• Development parameters and business rules (parameter list + acquisition steps + hybrid payment types and amount formulas + order status transitions + sensitive field encryption specifications + city ID and medical institution code acquisition):
  • Merchant mode → 📄 Merchant Mode Development Parameters and Business Rules
  • Service provider mode → 📄 Service Provider Mode Development Parameters and Business Rules
• Signature and verification rules (request signature / response verification / callback verification / payment invocation signature):
  • Merchant mode → 📄 Merchant Mode Signature and Verification Rules
  • Service provider mode → 📄 Service Provider Mode Signature and Verification Rules
• Callback handling (callback decryption / verification / idempotency / concurrency control):
  • Merchant mode → 📄 Merchant Mode Callback Handling
  • Service provider mode → 📄 Service Provider Mode Callback Handling

Capability 4: Integration Quality Assessment

When the user is preparing to go live or wants to check code for hidden risks → load the following documents.

‼️ Only check the functional modules the user actually uses. Modules such as payment on behalf of relatives, JSAPI invocation, Mini Program invocation, and medical insurance refund notification must first be confirmed whether the user is involved;do not check or mention those not used。

• Integration quality check (including quality inspector persona + checklist):
  • Merchant mode → 📄 Merchant Mode Integration Quality Check
  • Service provider mode → 📄 Service Provider Mode Integration Quality Check

Capability 5: Troubleshooting

‼️ Sole entry point: When the user reportsanyissue (error / API exception / callback not received / signature failure / amount verification failure / medical insurance bureau business error / business rule questions, etc.),first load the troubleshooting manual below according to the integration mode, and strictly follow the "Troubleshooting Process" in the manual;do not guess the cause on your own or directly analyze the code。

‼️ Error message first: When the user provides an official error message (such as "medical insurance settlement requires self-payment amount calculation failed"), first use the "Error Message Precise Hit Table" at the beginning of the manual for precise localization;do notdirectly skip to the TOP 20 error codes or general formula solutions; only when the user provides only a Request-Id / error code number should you go to the TOP 20.

‼️ After troubleshooting is complete, you must at the end of the replyproactively recommend the Integration Quality Assessment(Take the troubleshooting opportunity to also check for other potential issues in one pass); if sample code recommendations are needed, first confirm the development language before recommending,When the user's language is not Java/Go, handle it according to the cross-language confirmation process in Capability 2(confirmation dialog → reference generation + disclaimer block + public library step-by-step).

• Troubleshooting Manual (Error Message Exact Match Table + I. Top 20 Error Codes + II. Common Issues, covering HTTP / Callbacks / Signatures / Refunds / Business Rules / General Configuration / Password-free Authorization / Family Authorization):
  • Merchant Mode → 📄 Merchant Mode Troubleshooting Manual
  • Service Provider Mode → 📄 Service Provider Mode Troubleshooting Manual

---

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

💬 Community and Feedback

If you encounter problems during use, have improvement suggestions, or want to exchange integration experience with other developers, you are welcome to scan the QR code to add the enterprise WeChat group and discuss with the official team and community developers: