微信支付医保支付接入skill

SKILL.md

---
name: wechatpay-medical-insurance-payment
description: 微信支付医保支付（移动医保支付2.0）接入解决方案，覆盖医保自费混合下单、订单查询、医保退款通知、医保收款回调全链路，提供选型/示例代码/业务速查/质量评估/排障五大能力。Use when user mentions "医保支付", "移动医保支付2.0", "医保自费混合", "医保电子凭证", "医保混合收款", "医保退款通知", "医保挂号", "医保诊间支付", "医保住院结算", "医保药店购药", "互联网医院医保", "医保定点机构", or asks to "接入医保支付", "要医保下单接口示例代码", "排查医保支付问题".
author: wechatpay
version: "1.0"
---

# 微信支付医保支付接入指引

## 全局交互规范

> ‼️ 以下规则适用于本技能所有能力、所有对话轮次，优先级高于各能力的局部规则。

1. **所有问题必须得到用户明确回答后才能继续。** 一次提出多个问题时，逐一检查是否都已获得明确答复，未答复的必须再次追问，**严禁自行假设、推断或使用默认值**。
2. **接入模式前置确认**：任何能力使用前须先确认 **商户模式** 或 **服务商模式**，已明确则无需重复。两种模式的核心差异（参数命名、API 路径、签名工具类）见各角色 `接入指南/签名与验签规则.md`。
3. **分步确认协议**（简单知识问答除外）：
   - **① 明确需求**：先理解问题给出初步判断，不要堆参数清单。
   - **② 征得同意**：主动提出下一步能做什么，等用户明确同意后才继续。
   - **③ 收集信息**：用户同意后再告知所需信息并逐项收集，收齐才执行。
   - **④ 执行前确认**：操作前简要说明即将做什么，确认同意后再执行；线上环境额外提示风险。

## 能力概览

1. **产品选型** — 了解移动医保支付2.0的功能定位、混合支付类型（纯自费 / 纯医保 / 医保自费混合）、订单类型（挂号 / 诊间 / 住院 / 药店 / 互联网医院等）与接入前提
2. **示例代码** — 医保自费混合下单、订单查询（混合订单号 / 商户订单号 / 从业机构订单号）、医保退款通知、JSAPI / 小程序调起医保自费混合支付、收款成功回调 全套接口
3. **业务知识速查** — 开发参数与业务规则（含医保城市 ID、医疗机构编码、医保电子凭证授权信息、敏感字段加密）、混合支付类型判定、金额公式、订单状态流转、签名验签、回调处理
4. **接入质量评估** — 通用安全雷达 + 医保支付专属雷达：金额公式合法性、敏感字段（姓名 / 身份证摘要）公钥加密、医保下单字段三选一约束、医保退款通知幂等、（服务商）`sub_mchid` 路由防串单
5. **问题排查** — 错误码 TOP 20 + 常见问题，覆盖 HTTP 错误 / 回调收不到 / 签名失败 / 金额校验失败 / 医保局业务错误 / 角色特有问题 / 通用接入配置

> 路由说明：能力 1 用于产品概念性问题与接入前提确认，已明确接入医保支付的可直接跳到能力 2/3。能力 2 与 3 可独立调用，但首次必须先完成"接入模式前置确认"。能力 5 命中错误码或常见问题后，必须在末尾推荐能力 4 做一次性自查。

## 能力1：产品选型

> 用户问「这个产品是什么 / 能做什么 / 适合什么场景 / 接入需要什么前提 / 商户和服务商怎么选 / 直连和间连什么区别」时 → 加载产品介绍文档作答。已明确接入医保支付的可直接跳到能力 2/3。

- 产品介绍（产品概览 + 使用场景 + 接入前提）：
  - 商户模式 → [📄 商户模式产品介绍](./references/1-商户/产品选型/产品介绍.md)
  - 服务商模式 → [📄 服务商模式产品介绍](./references/2-服务商/产品选型/产品介绍.md)

## 能力2：示例代码

> 用户要某个接口的示例代码时 → 确认接入模式和语言，加载对应模式的 `接口索引.md` 定位代码文件。
>
> ‼️ **只检索、不生成。** 严禁从零编写任何代码，必须从示例代码文件中检索获取。
>
> ‼️ **只展示、不写入。** 示例代码仅用于讲解 API 调用结构和签名流程，严禁直接写入用户项目（禁止调用 write_to_file、replace_in_file 等工具创建或修改项目文件），让用户自行复制适配。
>
> ‼️ **先交互、后输出。** 提供代码前必须先确认接入模式、开发语言和具体接口，每次只输出一个接口；提供完代码后主动推荐接入质量评估。
>
> ‼️ **用户语言非 Java/Go 时**（本 skill 仅维护 Java/Go 示例）：**禁止**直接生成跨语言代码。流程：
> 1. 用 `AskQuestion` 获明确同意（文案需明示「参考实现 / 非官方维护 / 须自行 review 与测试」），未同意只发官方 Java/Go 原文。
> 2. 同意后以官方 Java 示例为基准翻译生成业务代码「参考实现」；再用纯文字问是否翻 Java 公库（SDK 工具类 + HTTP 客户端），未明确要不贴。每段代码前附下方免责块。
>
> > ⚠️ 以下代码为**跨语言参考实现**，由 AI 参考官方 Java 示例翻译生成，并非微信支付官方维护。
> > - 请**逐行 review** 签名构造、HTTP 调用、字段命名、回调解密等关键逻辑。
> > - 上线前必须在测试环境完整验证，建议先以官方 Java/Go 示例打通主链路作为对照。
> > - 出现接入问题时以官方 Java/Go 示例为准。
>
> ‼️ **拉起端类型确认规则**：「调起医保自费混合支付」必须先确认拉起端类型（JSAPI 公众号 H5 / 小程序），不同端的报文与签名规则不同；其余通用接口（下单 / 查单 / 医保退款通知 / 收款成功回调）无需询问拉起端。

- 涉及提供示例代码时，按接入模式查阅对应接口索引：
  - 商户模式 → [📄 商户模式接口索引](./references/1-商户/示例代码/接口索引.md)
  - 服务商模式 → [📄 服务商模式接口索引](./references/2-服务商/示例代码/接口索引.md)

> **加载策略**：先确认接入模式，读对应的 `接口索引.md` 定位接口文件路径，再按需加载具体文件。不要一次性加载所有文件。

## 能力3：业务知识速查

> 用户问开发参数与业务规则（mchid / sub_mchid / appid / sub_appid / APIv3 密钥 / 商户 API 证书 / 微信支付公钥 / 城市 ID / 医疗机构编码 / 医保电子凭证授权信息）、混合支付类型判定、金额公式、订单状态流转、敏感字段加密、签名规则、回调机制等业务知识时 → 按接入模式加载对应文档。

- 开发参数与业务规则（参数清单 + 获取步骤 + 混合支付类型与金额公式 + 订单状态流转 + 敏感字段加密规范 + 城市 ID 与医疗机构编码获取）：
  - 商户模式 → [📄 商户模式开发参数与业务规则](./references/1-商户/接入指南/开发参数与业务规则.md)
  - 服务商模式 → [📄 服务商模式开发参数与业务规则](./references/2-服务商/接入指南/开发参数与业务规则.md)
- 签名与验签规则（请求签名 / 响应验签 / 回调验签 / 调起支付签名）：
  - 商户模式 → [📄 商户模式签名与验签规则](./references/1-商户/接入指南/签名与验签规则.md)
  - 服务商模式 → [📄 服务商模式签名与验签规则](./references/2-服务商/接入指南/签名与验签规则.md)
- 回调处理（回调解密 / 验签 / 幂等 / 并发控制）：
  - 商户模式 → [📄 商户模式回调处理](./references/1-商户/接入指南/回调处理.md)
  - 服务商模式 → [📄 服务商模式回调处理](./references/2-服务商/接入指南/回调处理.md)

## 能力4：接入质量评估

> 用户准备上线或想检查代码隐患时 → 加载以下文档。
>
> ‼️ **只检查用户实际使用的功能模块。** 代亲属支付、JSAPI 拉起、小程序拉起、医保退款通知 等模块须先确认用户是否涉及，**未使用的不检查、不提及**。

- 接入质量检查（含质检人设 + 检查清单）：
  - 商户模式 → [📄 商户模式接入质量检查](./references/1-商户/接入指南/接入质量检查.md)
  - 服务商模式 → [📄 服务商模式接入质量检查](./references/2-服务商/接入指南/接入质量检查.md)

## 能力5：问题排查

> ‼️ **唯一入口**：用户报告**任何**问题（报错 / 接口异常 / 回调收不到 / 签名失败 / 金额校验失败 / 医保局业务错误 / 业务规则疑问等），**都先按接入模式加载下方排障手册**，严格按手册内「排障流程」执行，**禁止自行猜测原因或直接分析代码**。
>
> ‼️ **文案优先**：用户给出官方报错文案（如「医保结算后需自费金额计算失败」）时，先走手册开头的「报错文案精准命中表」精准定位，**禁止**直接绕到 TOP 20 错误码或公式通解；仅当用户只给 Request-Id / 错误码数字时才走 TOP 20。
>
> ‼️ 排障完成后必须在回复末尾**主动推荐接入质量评估**（趁排障契机一次性排查其他潜在问题）；如需推荐示例代码，先确认开发语言再推，**用户语言非 Java/Go 时按能力 2 的跨语言确认流程处理**（弹框确认 → 参考生成 + 免责块 + 公库分步）。

- 排障手册（**报错文案精准命中表** + 一、错误码 TOP 20 + 二、常见问题，覆盖 HTTP / 回调 / 签名 / 退款 / 业务规则 / 通用配置 / 免密授权 / 亲情授权）：
  - 商户模式 → [📄 商户模式排障手册](./references/1-商户/问题排查/排障手册.md)
  - 服务商模式 → [📄 服务商模式排障手册](./references/2-服务商/问题排查/排障手册.md)

---

> 以下信息与技能能力无关，仅供查阅。

## 💬 社区与反馈

在使用过程中遇到问题、有改进建议，或者想和其他开发者交流接入经验，欢迎扫码添加企业微信进群，与官方团队和社区开发者一起讨论：

![微信支付 Skills 交流群二维码](https://raw.githubusercontent.com/wechatpay-apiv3/wechatpay-skills/main/wechatpay-basic-payment/assets/qrcode.jpg)