开发指引
更新时间：2026.04.171、开发前准备
开发前准备分为两部分：技术接入准备（1.1～1.4）和联调测试环境准备（1.5～1.7）。
1.1、设置安全联系人
微信支付日常安全监测发现技术异常时，会向安全联系人和超级管理员发送风险提醒。请商户超级管理员尽快设置技术同事为安全联系人，确保能及时接收异常信息评估业务风险，详见安全联系人设置指引。
1.2、熟悉微信支付接口规则
1.3、熟悉授权及模板消息接口文档
接入前，先阅读对应的接口文档，提前了解对应的细节，再进行开发，有利于高效开发。微信接口文档包括三部分：用户授权接入文档、订阅消息类文档（公众号模板消息、微信小程序订阅消息）。
1.4、准备开发参数
在发起接口请求时，开发者还需传入一些必要参数，如服务商商户号、子商户号（也叫特约商户号）、sp_appid、证书私钥、公钥等，获取方式详见：服务商模式开发必要参数说明。
|
1.5、电子凭证测试环境参保人准备
当测试环境联调通过后，方可进入生产环境调试。因此为确保测试流程顺利进行，医院测试人员需先在电子凭证测试环境中配置对应的参保人信息。
若当前环境中暂无相应参保信息，可整理以下所需测试人员信息，提交给微信联调人员或对应省份中台工作人员。如果各省份城市有对应的工作群，可以先把测试参保人信息提交给地市相关医保/中台负责人，提交到省里统一处理。
【电子凭证测试环境信息模板】
姓名：
证件号码：
证件类型：01（身份证）
参保地代码：
参保地名称：
1.6、微信测试环境测试人员准备
在微信测试环境中进行电子凭证激活与医保移动支付前，需完成以下操作：测试人员请先解绑微信正式环境中的电子凭证，随后将个人信息按以下模板提交给微信联调人员，以便添加至测试环境。完成添加后，方可在微信测试环境中使用。若后续需恢复正式环境使用，请联系微信联调人员解除测试环境配置。
提交信息模板：
姓名：
身份证：
手机号：
微信号：
1.7、授权小程序体验者权限添加
为在测试环境中调试医保移动支付授权流程，若医院通过微信小程序接入，需将体验者微信号提交给微信联调人员。添加后，该体验者可打开授权小程序的联调环境进行测试。体验者权限在医院的微信小程序正式上线医保移动支付后，定时进行删除。
【授权小程序体验者权限添加模板】
微信号：
调试医院：
|
2、整体业务开发流程概览
完整业务流程时序图详见本文「4、整体流程时序图」章节。
用户先进入缴费流程，完成缴费授权后，系统返回医保局支付授权码（pay_auth_no）及医保局订单（pay_order_id）。其中，pay_auth_no、pay_order_id 将作为后续非纯自费场景下服务商下单的重要入参。
若存在自费部分，需先调用自费下单接口获取预支付ID（prepay_id）等微信支付下单信息；若为非纯自费场景，则需携带医保局支付授权码（pay_auth_no）、医保局订单（pay_order_id）等调用医保自费混合收款下单接口，下单成功后返回医保自费混合订单号（mix_trade_no）等订单信息。
服务商在获取预支付ID（prepay_id）、应用ID（appid）、签名（paySign）等参数后，由小程序或公众号H5拉起医保支付流程。用户完成自费支付，若医保结算超时，微信医保应用系统会自动触发冲正，撤销已完成的医保结算并释放冻结资金。冲正成功后该笔订单不可再发起支付。服务商/子商户前端页面可接收到回调结果，服务商需进一步调用查看医保自费混合收款结果接口确认订单最终状态，并优先按使用医保自费混合订单号查看下单结果；若下单结果不明确，再按使用服务商订单号查看下单结果。服务商可根据查询结果展示支付状态并更新内部订单状态。医保混合收款成功后，微信支付还会向服务商发送医保混合支付成功回调通知。
自费部分可在服务商平台下载自费账单，医保部分可在医保局侧下载医保结算账单。
退款处理分为自费退款和医保退款两类：自费退款由服务商调用微信支付标准退款申请完成处理；医保退款由医保侧退款成功后，服务商调用医保退款通知接口进行退款结果同步，最终完成医保退款通知。
3、详细步骤说明
3.1、医院发起缴费
医院发起缴费阶段，覆盖从用户确认缴费金额、进入缴费流程，到完成医保授权及费用明细上传的全过程。若当前不是纯自费场景，医疗机构系统需要先向微信医保应用系统获取在线医保支付授权，并由微信医保应用系统进一步向医保系统获取授权结果。若当前在线医保支付授权不存在或已经过期，则需要先重新完成授权，再继续后续流程。
在拿到有效的医保支付授权码 pay_auth_no 后，医疗机构系统继续向医保系统发起医保费用预结算/确认，请求中会带上 pay_auth_no 和医疗费用清单。医保系统完成处理后，返回医保结算订单号 pay_order_id 以及本次医疗费用组合结果。随后医院完成费用明细上传，并将 pay_auth_no、pay_order_id 及医疗费用组合同步至服务商后台，作为后续“服务商下单”环节的重要输入。
医保侧返回参数说明
pay_order_id：医保局返回的支付单 ID。pay_auth_no：医保局返回的支付授权码。
关键说明
纯自费场景不依赖医保授权与医保费用确认流程，可直接进入自费下单链路。
非纯自费场景下，
pay_auth_no和pay_order_id是后续混合支付下单的关键入参，必须确保来源于同一笔有效的医保缴费上下文。若授权失效或授权状态不明确，应先重新完成授权，再继续医保费用确认，避免出现后续下单失败或医保结算不一致的问题。
3.2、服务商下单
3.2.1、自费下单
服务商通过调用JSAPI/小程序下单接口生成订单并获取预支付ID。
下单接口关键参数说明：
sub_mchid：子商户的商户号，也是订单对应的收款商户号，在订单支付成功后，订单收款的资金将进入该子商户的基本账户内。
openid：用户在服务商下单的sp_appid下唯一标识，获取方式详见参数说明。
sub_openid：用户在服务商下单的sub_appid下唯一标识，获取方式详见参数说明。
time_expire：支付结束时间。若传递该参数，则用户只能在订单设置的支付结束时间time_expire之前进行支付，超过支付结束时间后，用户支付将收到："订单已超过商户设置的最晚支付成功时间，请重新发起支付"的提示，服务商需对订单进行关单处理。若不传该参数，默认订单支付有效期为7天，用户可在7天内进行支付，超出7天，订单将被关闭。
prepay_id：预支付交易会话标识。调起支付时需要使用的参数，prepay_id有效期为2小时，超过2小时，服务商需要使用原下单参数重新请求下单接口，获取新的prepay_id。
profit_sharing：订单分账标识，如果订单在支付成功后需要进行分账，必须传参数值为true。如果无需分账，可以不传该参数，或传false。
3.2.2、医保自费混合收款下单
完整业务流程时序图详见本文「4、整体流程时序图」章节。
服务商通过调用医保自费混合收款下单接口，创建医保自费混合支付订单。该接口支持纯自费、纯医保和医保自费混合三种支付类型。下单成功后，接口返回 mix_trade_no（医保自费混合订单号）及调起支付所需的参数。
下单接口关键参数说明：
mix_pay_type：混合支付类型。枚举值：CASH_ONLY（纯自费支付）、INSURANCE_ONLY（纯医保支付）、CASH_AND_INSURANCE（医保自费混合支付）。
sub_mchid：医疗机构的商户号（服务商模式下即子商户号）。
openid / sub_openid：二选一。传入 openid 时需使用 appid 调起支付，传入 sub_openid 时需使用 sub_appid 调起支付。
out_trade_no：服务商订单号。含自费场景下，服务商需先调用微信支付下单接口（带上 out_trade_no），再调用本接口（也带上 out_trade_no），两次请求中的 out_trade_no 应保持一致。纯医保下单时，沿用医院传过来的 out_trade_no 即可。
serial_no：医疗机构订单号（如医院 HIS 系统订单号）。需与【6201】费用明细上传中 medOrgOrd 字段值一致，局端会校验，不一致将导致支付失败。
pay_order_id：医保局返回的支付单 ID。纯医保支付或医保自费混合支付时必填，纯自费支付时禁止填写。
pay_auth_no：医保局返回的支付授权码。纯医保支付或医保自费混合支付时必填，纯自费支付时禁止填写。
total_fee：使用该接口下单的总金额，单位分。total_fee = med_ins_gov_fee + med_ins_self_fee + med_ins_other_fee + wechat_pay_cash_fee + cash_reduce_detail。
wechat_pay_cash_fee：实际需要用户微信支付的金额，单位分。纯自费支付或医保自费混合支付时必填，纯医保支付时禁止填写。
prepay_id：微信支付预支付交易会话标识，来源于自费下单接口，有效期 2 小时。纯自费支付或医保自费混合支付时必填，纯医保支付时禁止填写。
callback_url：回调通知 URL，必须为 HTTPS 地址，不允许携带查询串。
关键返回参数说明：
mix_trade_no：医保自费混合订单号，后续查单时优先使用该字段。
3.3、服务商调起医保支付
服务商在下单成功后，根据前端载体不同，分为 JSAPI调起医保自费混合支付和小程序调起医保自费混合支付两种方式。
调起支付关键参数说明：
mixTradeNo：混合收款单 ID，来源于医保自费混合收款下单接口返回的 mix_trade_no。
3.4、用户支付
用户在微信收银台完成支付或取消支付后，返回服务商前端/小程序页面。此时微信浏览器内置对象/小程序会向前端返回支付流程结果回调，服务商需调用查询订单 API 接口确认订单状态，并根据查单结果向用户展示支付结果。查单支持两种方式：优先按使用医保自费混合订单号查看下单结果；若下单结果不明确（如未拿到 mix_trade_no），再按使用服务商订单号查看下单结果。
如果用户支付成功，微信支付系统还会异步向服务商发送医保混合收款成功通知。若服务商在 30 秒内未收到回调，应主动调用查单接口确认订单状态。具体实现方案服务商可以参考支付回调和查单实现指引。
按 mix_trade_no 查单关键请求参数：
mix_trade_no：医保自费混合订单号，下单成功时返回。优先使用该字段查单。
按 out_trade_no 查单关键请求参数：
out_trade_no：商户系统内部订单号。
关键返回参数说明：
mix_pay_status：医保自费混合订单支付状态。枚举值：MIX_PAY_CREATED（等待支付）、MIX_PAY_SUCCESS（支付成功）、MIX_PAY_REFUND（自费和医保均已退款）、MIX_PAY_FAIL（支付失败）。
self_pay_status：混合订单中自费部分的支付状态。枚举值：SELF_PAY_CREATED（等待支付）、SELF_PAY_SUCCESS（支付成功）、SELF_PAY_REFUND（已退款）、SELF_PAY_FAIL（支付失败）、NO_SELF_PAY（订单不含自费部分）。
med_ins_pay_status：混合订单中医保部分的支付状态。枚举值：MED_INS_PAY_CREATED（等待支付）、MED_INS_PAY_SUCCESS（支付成功）、MED_INS_PAY_REFUND（已退款）、MED_INS_PAY_FAIL（支付失败）、NO_MED_INS_PAY（订单不含医保部分）。
若因特殊原因需在用户可支付时间范围内关闭订单，自费部分可调用微信支付基础关闭订单API 接口，医保部分需要在医保局侧进行关单处理。
3.5、冲正
详细参考：冲正流程与处理机制
3.6、对账
自费部分可在服务商平台申请所有/单个特约商户交易账单，医保部分可在医保局侧下载医保结算账单。
3.7、退款
退款处理分为自费退款和医保退款两类，需分别处理。
自费退款： 服务商调用微信支付申请退款接口发起自费部分的退款。退款成功后，退款金额将原路返回至用户支付账户。
医保退款： 医保部分的退款由医保侧处理完成后，服务商调用医保退款通知接口接收医保退款结果，完成退款闭环。需要注意的是，医保退款除线上流程外，医院也可通过线下窗口直接办理，线下退款流程不经过微信支付系统。
医保退款通知接口关键参数说明：
mix_trade_no：医保自费混合订单号。
out_refund_no：服务商退款单号。有自费单时，应填与申请退款处一致的 out_refund_no；否则透传医疗机构退款单号即可。
med_refund_total_fee：医保退款的总金额，单位分。
med_refund_gov_fee：医保统筹退款金额，单位分。
med_refund_self_fee：医保个账退款金额，单位分。
med_refund_other_fee：医保其他退款金额，单位分。
refund_time：医保退款成功时间，格式为 yyyy-MM-DDTHH:mm:ss+TIMEZONE。
4、整体流程时序图
|
5、附录
5.1、API参考文档
详情见API列表
