接入易错点

 纯自费订单应直接使用基础JSAPI支付

 说明：纯自费订单不依赖医保授权和医保费用确认流程，可直接调用微信支付基础 JSAPI/小程序下单完成收款，查询和退款也调用基础支付接口；不应为纯自费代付订单虚构医保支付人实名信息。
正确应该怎么做：① 根据费用构成判断订单是否含医保金额；② 不含医保金额的订单跳过医保授权与医保混合下单；③ 调用基础 JSAPI/小程序下单取得 prepay_id，再拉起基础微信支付；④ 查询和退款分别调用基础支付查单、退款接口；⑤ 若选择纯自费走医保混合下单接口，则按 CASH_ONLY 规则传参，不使用医保授权字段。
典型反例：允许他人的微信替患者支付纯自费订单，却仍要求其走医保混合下单并填写患者的 payer 身份信息。
见 4016824681-开发指引、4017415831-业务&接口规则类问题、4013071036-申请退款 

 纯自费订单被错误纳入医保授权及混合下单链路，无法按实际付款人完成支付，业务无法继续。

 零费用订单不得发起医保支付

 说明：医保下单同时要求医保金额与微信自费金额不能全部为 0；0 费用挂号不应进入医保支付流程。
正确应该怎么做：发起医保预结算或医保下单前先校验应收金额；总额为 0 时直接按业务规则完成零费用处理，不调用医保支付接口。
见 4016781466-医保自费混合收款下单 

 医保预结算或下单失败，订单无法继续支付；接口还可能返回「实际需要用户微信支付的金额和医保下单的金额都为0，无法下单」。

 医保授权与下单须使用同一环境

 说明：医保授权和下单必须处于同一环境，测试授权对应测试下单，正式授权对应正式下单；测试与正式环境的接口、密钥和授权反馈单参数须成套使用。
正确应该怎么做：① 测试环境使用测试授权地址、测试反馈单参数及测试partnerSecret；② 正式环境使用正式授权地址、正式反馈单参数及正式partnerSecret；③ 混合下单时用med_ins_test_env=true指定医保局测试环境，正式环境传false或不传；④ 上线前逐项核对授权地址、应用ID、渠道编码、密钥及med_ins_test_env是否属于同一环境。
典型反例：请求已切到正式地址，但仍沿用测试密钥或测试反馈单参数。
见 4016781466-医保自费混合收款下单、4017415831-业务&接口规则类问题、4021773498-测试及环境切换、4016824681-医保支付开发指引 

 返回“签名不正确”或“请求移动支付地址失败”；授权与下单混用环境时返回“未找到对应授权信息”，无法进入医保授权或完成下单；另可能返回 INVALID_REQUEST。 

 医保授权与支付须在手机微信完成

 说明：医保支付收银台支持公众号 H5 和小程序，但不支持 PC 微信；公众号 H5 还须完成 wx.config 鉴权并在 wx.ready 中调用拉起接口。
正确应该怎么做：① 通过手机微信打开公众号 H5 或小程序；② 公众号 H5 的 wx.config 将 requestMedicalInsurancePay 加入 jsApiList，在鉴权成功后的 wx.ready 回调中调用拉起接口；③ 医院侧移动支付授权也按手机端指引完成，不设计 PC 端授权入口。
见 4020401138-医保支付报错排查指引、4016781549-JSAPI调起医保自费混合支付、4017415831-业务&接口规则类问题 

 公众号 H5 可能返回 system:access_denied 或 no permission to execute，PC 端无法拉起医保支付，用户无法付款。

 医保测试须从医院体验版跳转授权

 说明：医保测试环境联调须先添加医院小程序的体验者权限，并由医院侧体验版小程序进入医保授权体验版；授权环境与下单环境须保持一致。
正确应该怎么做：① 将医院测试人员微信号提交给微信联调人员，添加为授权小程序体验者；② 从医院体验版小程序入口进入医保支付流程；③ 核对授权环境与 med_ins_test_env 参数一致，测试授权对应测试下单；④ 测试完成后替换正式反馈单参数、正式回调地址和正式环境配置。
典型反例：使用正式小程序直接跳转医保授权页，实际请求落到正式环境；或测试授权与正式下单混用。
见 4021773498-测试及环境切换、4020401138-报错排查指引、4016824681-开发指引、4017415831-业务&接口规则类问题 

 授权请求实际进入正式环境，出现授权报错或「未找到对应授权信息」，医保测试联调无法完成。

 授权成功后须回跳商户页面继续办理

 说明：用户完成医保授权后，流程须回到商户自有小程序或页面，由商户系统继续完成费用明细上传、预结算及后续结算；回跳目标须由商户正确配置并能够继续处理授权结果。
正确应该怎么做：① 在授权链接中配置商户自己的回跳页面；② 确认用户完成授权后能够从微信医保授权页返回该页面；③ 前端取得 authCode 后交给商户后端调用授权查询接口；④ 后端取得 pay_auth_no、pay_order_id 等结果后继续费用明细上传及预结算；⑤ 回跳后展示明确的加载状态，避免长时间接口调用期间出现空白页。
典型反例：只验证授权页本身是否成功，未核对授权完成后的回跳地址和商户页面初始化逻辑，导致用户授权成功后停留在白屏页面。
见 4016824681-开发指引、4016824672-产品介绍 

 用户虽已完成医保授权，但无法回到商户业务页面继续办理，费用明细上传和预结算流程无法继续。

 authCode须及时换取payAuthNo

 说明：非纯自费场景须使用有效的医保支付授权码；授权不存在或已过期时，应重新完成授权并取得新的授权码，再继续费用确认和下单流程。
正确应该怎么做：① 前端完成医保授权后取得新的 authCode；② 后端以 authCode 作为 qrcode 调用授权查询接口，换取 pay_auth_no 等参数；③ 确认授权环境与下单环境一致；④ 使用新授权码完成预结算、费用明细上传和混合下单；⑤ 不继续复用已失效的授权码或旧授权链接。
典型反例：用户已经完成过医保授权，就直接复用旧授权码下单，不再检查授权是否失效。
见  https://docs.qq.com/doc/DV3JYRG1xelhKTWdz 、4020401184-报错排查指引、4016824681-开发指引、4020401138-报错排查指引、微信医保移动支付接口文档 

 授权查询返回 code=500707、message=授权码已失效，医保下单无法继续，当天挂号或结算报错。 

 userQuery与city_id须覆盖用户参保地

 说明：city_id 是医保下单的地区参数，部分地区与标准地区编码有差异；授权与下单应使用一致的城市和运行环境。上海国标为 310002、非国标为 310000；city_id 由腾讯侧对接时提供（如青岛为 370201），不能直接用公开行政区划码替代（如 370200）。
正确应该怎么做：①根据医院实际接入地区和用户默认参保地取得对应 city_id；②测试环境与正式环境分别配置对应参数；③将 city_id 与 pay_auth_no、med_ins_test_env 一并核对；④非国标地区按当地要求传入对应 city_id。
典型反例：在两个环境中硬编码同一个 city_id，或从其他小程序复制参保地参数后直接复用。
见 4012503131-医保自费混合收款下单、4020401184-报错排查指引、4021773695-测试及环境切换、4016781466-医保自费混合收款下单、4020801245-错误码 

 city_id 与授权参保地或运行环境不一致时，可能提示「未找到对应授权信息」，医保授权或下单无法继续；另可能返回 INVALID_REQUEST，提示「医保局结算校验失败，请确认医保相关的字段是否正确」。 

 小程序授权链接不得重复编码机构渠道编码

 说明：小程序免密授权时，机构渠道认证编码应与反馈单一致；报错排查指引说明，小程序授权链接中的机构渠道认证编码不需要编码。
正确应该怎么做：①从小程序授权链接中取出 orgChnlCrtfCodg；②使用反馈单中的原始值拼接；③避免从其他环境或其他产品复制已编码的链接；④完成后重新发起授权并确认能正常返回授权结果。
典型反例：从个人医保支付或其他 H5 场景复制已 URL 编码的授权链接，再直接用于小程序。
见 4020401184-医保支付（服务商模式）报错排查指引 

 家庭账户等授权请求报错，用户无法完成医保授权，后续无法继续下单。

 6201费用明细须传完整诊断信息

 说明：医保接入需对接局方【6201】费用明细上传接口；diseinfoList 为空会导致医保参数校验失败。
正确应该怎么做：① 调用【6201】前从本次就诊信息构造非空的 diseinfoList；② 按当地医保接口要求填写诊断编码、诊断名称等字段，不得传 null 或空列表；③ 完成费用明细上传并取得成功响应后，再继续预结算和医保下单。
见 4016824684-开发接入准备 

 返回 360053，提示「054处方上传失败，FSI-[FSI]参数校验异常：诊断信息不能为空」，费用明细无法上传，后续挂号支付流程无法继续。 

 医保下单serial_no须与medOrgOrd一致

 说明：医保自费混合收款下单的 serial_no 是医疗机构订单号，须与 6201 费用明细上传中的 medOrgOrd 完全一致；局端会校验该字段。
正确应该怎么做：① 在费用明细上传前生成并保存医院业务订单号；② 6201 上传时作为 medOrgOrd 传递；③ 混合下单时原样复用为 serial_no，不得重新生成或截断；④ 多个 out_trade_no 可以对应同一个 serial_no，重新下单时保持业务单据号不变。
典型反例：费用上传由 HIS 生成一个机构流水号，混合下单又由支付中台另生成一个流水号。
见 4016781466-医保自费混合收款下单、4012503131-医保自费混合收款下单（服务商模式）、4020401138-报错排查指引、4016781490-使用商户订单号查看下单结果、4016824681-开发指引、4018300080-医保自费混合收款下单 

 局端校验不一致导致支付失败；用户输入支付密码后提示「支付未成功」，无法完成医保结算；另可能返回 INVALID_REQUEST。 

 签名时间戳须按接口时限校验

 说明：医保获取用户信息接口会校验请求头时间戳，客户端时间与服务端标准时间偏差超过 1 分钟时返回签名超时。
正确应该怎么做：① 服务器启用 NTP 或等价时间同步；② 每次请求按标准时间生成 god-portal-timestamp；③ 签名串中的时间戳与实际请求头保持一致；④ 监控服务器时间偏移，发现偏移时先校准再重试。
典型反例：客户端设备时间自行设置，或使用本地缓存时间生成请求头与签名。
见 4012072670-为什么请求返回401 Unauthorized？、微信医保移动支付接口文档、4012365342-总述-APIv3如何签名和验签 

 接口返回 requestId 对应的「签名超时」，医保用户信息查询失败，后续授权或支付流程无法继续；另可能返回 100019。 

 wxAuthData请求头须携带合规签名

 说明：旧版医保移动支付授权调用 wxAuthData 时，请求头中的签名须完整传递，签名长度须符合接口要求的 64 位或 32 位。
正确应该怎么做：① 在统一请求封装中为 wxAuthData 请求构造并写入签名请求头；② 发送前校验签名非空、长度符合要求，避免被截断或遗漏；③ 保留请求日志与 requestId，接口通过后再进入后续支付流程。
见 4012365342-总述-APIv3如何签名和验签 

 接口返回 code=100005，提示「signature长度不对，必须是64或32位」，医保授权无法完成，后续支付流程无法继续。 

 APIv3签名证书与序列号须保持同套

 说明：APIv3 请求签名所用的商户 API 证书私钥、请求头中的商户证书序列号须来自同一套证书；敏感字段加密所使用的微信支付公钥及其 ID 是另一套配置。
正确应该怎么做：① 固定一套当前有效的商户 API 证书及私钥用于请求签名；② 从该证书读取当前 serial_no 并放入 Authorization；③ 使用微信支付公钥及对应公钥 ID 处理敏感字段；④ 更换证书后同步替换私钥、序列号和相关配置。
典型反例：多次下载或生成证书后，混用不同批次的私钥、证书和公钥文件。
见 4013070756-开发必要参数说明、4013053257-如何使用微信支付公钥加密敏感字段、4012072670-为什么请求返回401 Unauthorized？ 

 请求验签失败，医保支付无法发起；更换配置后若仍混用旧文件，问题会持续存在。

 敏感字段加密须匹配公钥与Wechatpay-Serial

 说明：敏感字段须使用微信支付公钥或平台证书公钥加密，请求头 Wechatpay-Serial 必须与加密所用公钥匹配，加密算法须使用 RSAES-OAEP，推荐 SHA-256。医保自费混合收款下单的 APIv3 客户端可直接按普通商户公钥流程初始化（配置微信支付公钥 ID 与公钥文件），敏感字段用同一公钥加密。
正确应该怎么做：① 确认当前使用微信支付公钥还是平台证书公钥；② 用对应公钥加密 payer.name、payer.id_digest 等敏感字段；③ 将同一公钥的 ID 或证书序列号放入 Wechatpay-Serial；④ 使用 RSAES-OAEP(SHA-256) 完成加密。
见 4016913151-调用接口报错：“平台私钥解密失败” 

 下单返回 400 PARAM_ERROR，提示「平台私钥解密失败」，医保订单无法创建。 

 payer.id_digest须先MD5再公钥加密

 说明：payer.id_digest 是个人身份ID摘要，须先对证件号码计算MD5，得到的摘要为数字和小写字母组合，再使用微信支付公钥加密。证件号码中如有字母，文档示例要求转为大写后再计算MD5（示例使用大写X）；居民身份证为15位时须先转换为18位。
正确应该怎么做：① 从本次付款人的有效证件信息取得证件号码，15位身份证先补全为18位；② 证件号码含字母时按文档示例转为大写，再计算MD5得到32位十六进制摘要，并与文档示例结果核对；③ 使用微信支付公钥加密摘要后传入 payer.id_digest；④ payer.name、payer.id_digest、payer.card_type 须与医保电子凭证绑卡信息保持一致；⑤ 上线前使用同一测试患者核对加密结果可被正常解密。
典型反例：直接传明文证件号码；未做15位转18位，或末位X的大小写处理与文档示例及绑卡摘要口径不一致；摘要计算与公钥加密使用了两套不一致的证件值。
见 4016781466-医保自费混合收款下单、4012503131-医保自费混合收款下单（服务商模式）、4013053257-如何使用微信支付公钥加密敏感字段、4013059044-如何使用微信支付公钥加密敏感字段、4013038589-常见问题、4020401184-报错排查指引 

 医保下单返回 400 INVALID_REQUEST，提示「入参个人身份ID摘要和医保电子凭证绑卡身份ID摘要不匹配，请检查后重试」或身份信息校验失败，订单无法创建；另可能返回 INVALID_REQUEST。 

 payer与relative姓名须直接公钥加密

 说明：亲情代付中 payer 传实际付款人，relative 传就诊亲属；payer.name 与 relative.name 均须按微信支付公钥加密规则单独加密，不能互换或复用同一姓名。
正确应该怎么做：① 从绑定关系确认付款人和就诊亲属的实名信息；② 分别组装 payer 与 relative 三个字段；③ 对两个姓名分别使用微信支付公钥加密，并在请求头传递对应 Wechatpay-Serial；④ 同步核对 payer.id_digest 与 relative.id_digest 的摘要和加密处理；⑤ 提交前校验 pay_for_relatives=true 时 relative 完整存在。
典型反例：付款人和亲属姓名使用同一份加密结果，或只加密 payer.name、让 relative.name 使用明文。
见 4016781466-医保自费混合收款下单、4012503131-医保自费混合收款下单（服务商模式）、4013053257-如何使用微信支付公钥加密敏感字段、4016975471-接入医保亲情付指引、4020401138-报错排查指引 

 下单返回「入参用户姓名和医保电子凭证绑卡姓名不匹配，请检查后重试」，或返回 payer.name、relative.name 异常，亲情代付无法继续；另可能返回 INVALID_REQUEST。 

 医保支付人身份须与电子凭证一致

 说明：payer.name 须为付款人的真实姓名，使用微信支付公钥加密后上传，并须与医保电子凭证绑卡姓名一致；代办或亲属支付时，payer 节点传当前绑卡人信息。
正确应该怎么做：① 从医保电子凭证绑卡信息取得姓名，不由前端自由填写；② 用户确认姓名与证件信息后，使用微信支付公钥加密；③ 同时核对 payer.name、payer.id_digest、payer.card_type 与绑卡信息一致；④ 亲属支付时，payer 传绑卡人，relative 传亲属信息。
典型反例：用就诊人、代办人或家属姓名替代医保电子凭证绑卡人姓名。
见 4016781466-医保自费混合收款下单、4020401138-报错排查指引、4013053257-如何使用微信支付公钥加密敏感字段、4017415831-业务&接口规则类问题 

 医保下单返回 400 INVALID_REQUEST，提示「入参用户姓名和医保电子凭证绑卡姓名不匹配，请检查后重试」，订单无法创建。 

 医保亲情付须使用有效且一致的亲属关系

 说明：代亲属支付时，relative 节点传就诊亲属信息，payer 节点传实际付款人信息，支付授权码应为对应亲属的亲情授权码；授权与下单使用的亲属身份信息须与医保侧有效绑定记录一致。
正确应该怎么做：①先在医保侧确认付款人与就诊人的亲属关系有效；②亲情授权链接按就诊亲属信息生成 familyid，取得亲情授权码；③混合下单时分别传入付款人和亲属信息；④患者姓名等实名信息变更后，重新确认或建立有效亲属绑定，再重新授权和下单。
见 4016975471-接入医保亲情付指引、4016781466-医保自费混合收款下单、4020801245-医保支付错误码 

 混合下单返回 INVALID_REQUEST，提示「亲属关系不存在，请传入有效亲属关系后重试」，亲情医保支付无法继续。 

 混合下单前须完成医保预结算并按结果填值

 说明：只要院内减免后 wechat_pay_cash_fee 仍大于 0，就属于医保自费混合支付，mix_pay_type 应设为 CASH_AND_INSURANCE；应先调用基础支付统一下单取得 prepay_id，再调用医保自费混合收款下单，且两次下单的 out_trade_no 必须一致。
正确应该怎么做：① 以减免后的最终微信应付金额作为基础支付下单的 amount；② 调用 JSAPI 或小程序下单取得 prepay_id；③ 以同一 out_trade_no 调用医保自费混合收款下单，传 prepay_id、wechat_pay_cash_fee、pay_auth_no 和 pay_order_id；④ 保存返回的 mix_trade_no 用于拉起支付和查单。
典型反例：减免后仍需用户支付，却把订单按 INSURANCE_ONLY 提交，导致自费部分没有基础支付单。
见 4016781466-医保自费混合收款下单、4012503131-医保自费混合收款下单（服务商模式）、4020401138-报错排查指引、4016824681-医保支付开发指引、4017415831-业务&接口规则类问题 

 wechat_pay_cash_fee、prepay_id 与混合支付类型不匹配，下单返回字段或金额规则校验错误，用户无法完成微信自付部分；另可能返回 PARAM_ERROR、RULE_LIMIT、MED_INS_PAY_FAIL、INVALID_REQUEST。 

 零自费须免自费下单仅传mixTradeNo

 说明：INSURANCE_ONLY 适用于只向医保局下单、无需用户再向微信支付现金的场景，包括医保分账仍有自费金额但已被现金减免抵扣、实际微信支付金额为零的情况。med_ins_cash_fee 应按医保局结算结果填写；实际微信支付金额按 wechat_pay_cash_fee = med_ins_cash_fee + cash_add_detail - cash_reduce_detail 计算。
正确应该怎么做：① 按医保局结算结果分别填写统筹、个账、其他和结算后自费金额；② 计算现金补充与减免后的实际微信支付金额；③ 结果为零时选择 mix_pay_type=INSURANCE_ONLY，不再创建自费预下单，不填 wechat_pay_cash_fee 和 prepay_id；④ 调用医保自费混合收款下单后用返回的 mix_trade_no 拉起医保支付。
典型反例：减免后仍需实际支付为零，却继续使用 CASH_AND_INSURANCE 并传入 wechat_pay_cash_fee=0；或仅为体现减免而把医保局结算后的 med_ins_cash_fee 直接改成 0。
见 4017415831-业务&接口规则类问题、4016781466-医保自费混合收款下单、4016781545-小程序调起医保自费混合支付、4017415847-业务&接口规则类问题、4017149893-开发指引、4012166993-小程序调起医保自费混合支付、4016824704-开发接入准备、4016824684-开发接入准备、4012503131-医保自费混合收款下单、4020401138-报错排查指引、4020401184-报错排查指引 

 使用混合支付类型但微信实付金额为 0 时，会返回 RULE_LIMIT，提示自费下单金额与医保下单金额校验不通过，无法完成下单。 

 共济钱包金额须计入med_ins_self_fee

 说明：个人账户共济支付的资金口径属于医保个账支付，应作为医保个账支出统一填入 med_ins_self_fee，无需按共济资金来源拆成多笔医保金额字段。
正确应该怎么做：① 从医保预结算结果读取个人账户共济支付的合计金额；② 统一计入 med_ins_self_fee；③ 没有其他津贴支付时，不另拆金额到 med_ins_other_fee；④ 按字段公式参与 total_fee 计算；⑤ 结算后金额为 0 的医保必填字段仍按接口要求明确传递。
典型反例：按共济出资人来源拆成多条金额，或把共济金额重复填入个账与其他金额字段。
见 4016781466-医保自费混合收款下单、4016824681-开发指引、4017415831-业务&接口规则类问题 

 共济金额未计入个账金额或与其他金额字段重复，可能导致金额合计校验失败或医保结算金额不一致。

 APIv3 自费下单 amount.total 只能填写自费部分，不能填整单金额

 说明：自费下单是独立的基础支付订单，其订单金额应为该自费订单实际需要用户支付的金额，不应把医保统筹、个账等其他支付部分重复计入；APIv3 使用 amount.total。
正确应该怎么做：① 从同一笔医保预结算结果确认自费部分金额；② APIv3 基础下单接口设置 amount.total；③ 在医保混合下单中再按字段定义分别填写 med_ins_gov_fee、med_ins_self_fee、med_ins_other_fee、med_ins_cash_fee 和 wechat_pay_cash_fee；④ 按接口公式校验整单总金额，不使用自费订单金额代表整笔医疗费用。
典型反例：医保结算需自费 39.75 元、医保支付 119.25 元时，把 159 元整单金额填入自费订单金额字段。
见 4012791856-JSAPI下单、4016824681-开发指引、4016781466-医保自费混合收款下单 

 自费订单金额与医保混合订单金额不一致，混合下单金额校验失败，用户无法完成支付。

 医保标准字段须由顶层参数传入

 说明：pay_auth_no、pay_order_id、geo_location 等医保标准字段应使用顶层参数；passthrough_request_content 只承载地方医保业务数据，不应重复放入这些标准字段。
正确应该怎么做：① 从本次医保授权及预结算结果取得 pay_auth_no、pay_order_id；② 将 pay_auth_no、pay_order_id、geo_location 分别传入顶层字段；③ 透传内容仅放地方业务扩展数据，并在下单后通过查单或通知核对地方侧是否接收到。
见 4016781466-医保自费混合收款下单 

 下单可能成功且结算无报错，但医保中台缺少所需业务数据，医院侧无法完成业务记录或后续处理。

 地方扩展参数须按当地医保局结构传入

 说明：passthrough_request_content 的具体结构沿用地方医保局定义。山东医保场景应由局方文档规定的 request_content 承载，扩展业务数据放在 extData 内，不能自行增加参数名。
正确应该怎么做：① 取得当地医保局针对该接口的字段文档；② 按文档构造 request_content；③ 将本地业务扩展项放入 extData，标准医保字段仍按顶层要求传入；④ 联调时以省医保局中台实际取得的参数为准核对一次。
见 4016781466-医保自费混合收款下单 

 微信支付侧可能不报错，但省医保局中台取不到扩展字段，业务数据无法入库。