更新保单信息
更新时间:2026.01.14当保单信息变更,如出单成功、用户退保、保单失效等,商户需调用此接口实时同步更新保单信息。
● 状态流转规则:更新保单状态时需遵循以下规则,非法流转将导致更新失败:
出单中:可更新为已承保、已失效或拒保。
已承保:仅可更新为已失效(如退保、到期)。
已失效:支持更新为已承保(用于保单复效场景)。
拒保:属于终态,不支持流转至其他任何状态。
接口说明
支持商户:【普通商户】
请求方式:【PATCH】/v3/inspolicymgr/deduct/policies/{out_insurance_no}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
Wechatpay-Serial 必填 string
【微信支付公钥ID】或【微信支付平台证书序列号】 请求参数中的敏感字段,需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引;也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号、平台证书加密敏感信息指引
path 路径参数
out_insurance_no 必填 string(32)
【商户保险编号】 商户侧的保单唯一值,商户自定义字段,商户侧需保证该商户号下的唯一性。只能是数字、大小写字母的组合。字段作为整个保单管理流程的保单的唯一标识
body 包体参数
insured_name_list 选填 array[string(1024)]
【被保险人姓名列表】 被保险人姓名全称:单被保人时传入对应的姓名,多被保人时传入数组,最多允许传入11人;传空表示不更新,非空会用新列表覆盖旧列表;该字段需加密,请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引,也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号、平台证书加密敏感信息指引。
insurance_name 选填 string(50)
【保险名称】 用户投保的保险名称,用于展示给用户
effective_time 选填 string(25)
【保单生效时间】 标识保单保障期的起始时刻,从该时刻起(含边界)保单处于保障中状态。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。
expired_time 选填 string(25)
【保单失效时间】 标识保单保障期的结束时刻,在该时刻之前(不含边界)保单处于保障中状态。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。必须满足:保单失效时间大于保单生效时间: expired_time > effective_time
coverage_detail 选填 string(1000)
【保障详情】 保单对应的保障责任及保额,最多支持传入1000个字符;微信前端展示时,若内容大于等于998个字符,将从第998位截断并在末尾展示英文省略号。可参考:房屋主体损失:100万元;室内装潢损失:10万元;室内财产损失:10万元;水暖管爆裂损失:1万元;室内财产盗抢损失:2万元。
support_renewal 选填 boolean
【是否支持续保】 标识该保单是否支持续保功能
start_renewal_time 选填 string(25)
【可续保开始时间】 标识续保窗口的起始时刻,从该时刻起(含边界)允许发起续保。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。必须满足:(1)支持续保(support_renewal=true)时必填 (2)位于保障期内(含起含止):effective_time < start_renewal_time ≤ expired_time
end_renewal_time 选填 string(25)
【可续保结束时间】 标识续保窗口的结束时刻,在该时刻之前(不含边界)允许发起续保。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。必须满足:(1)支持续保(support_renewal=true)时必填 (2)大于可续保开始时间: end_renewal_time > start_renewal_time (3)不晚于保障期结束时间后60天: end_renewal_time ≤ expired_time + 60天。
policy_type 选填 string
【保单类型】 保单类型
可选取值
POLICY_TYPE_OTHER: 其余险POLICY_TYPE_MEDICAL: 医疗险POLICY_TYPE_ACCIDENT: 意外险POLICY_TYPE_CRITICAL: 重疾险POLICY_TYPE_CAR: 车险POLICY_TYPE_LIFE: 人寿险POLICY_TYPE_PROPERTY: 家财险POLICY_TYPE_PET: 宠物险POLICY_TYPE_ANNUITY: 年金险
car_number 选填 string(10)
【车牌信息】 保单类型为车险(policy_type=POLICY_TYPE_CAR)时,必传
pet_name 选填 string(10)
【宠物名称】 保单类型为宠物险(policy_type=POLICY_TYPE_PET)时,如果有,建议传入,会在微信保单服务展示给用户看
address 选填 string(300)
【地址信息】 保单类型为家财险(policy_type=POLICY_TYPE_PROPERTY)时,如果有,建议传入,会在微信保单服务展示给用户看
policy_state 选填 string
【保单状态】 保单当前的状态。可根据业务实际进度将其指定为出单中、已承保、已失效、拒保中的任一状态。状态变更时请参考保单状态转移矩阵确认是否可以更新。
可选取值
POLICY_STATE_ISSUING: 【出单中】正在进行出单操作,保险公司还未通过承保请求POLICY_STATE_APPROVED: 【已承保】保险公司已承保,保单处于保障待生效或保障中状态POLICY_STATE_DECLINED: 【拒保】保险公司拒绝承保或出单失败POLICY_STATE_INACTIVE: 【已失效】因各种问题,保单失效(用户退保、保单到期、欠费失效、理赔额度用尽等)
policy_code 选填 string(64)
【保司保单号】 保司承保后,为用户保单分配的唯一标识。保单状态为已承保、已失效时,必传。保单号将在前端展示给用户。已同步过(上传或更新保单信息设置过)不允许修改。
plan_id 选填 string
【保险委托代扣模板ID】 是商户在微信支付保险委托代扣平台申请模板,得到的唯一标识。
out_contract_code 选填 string(32)
【商户签约协议号】 商户侧的签约协议号,商户自定义字段,商户侧需保证唯一性。只能是数字、大小写字母的组合。
policy_periods 选填 array[integer]
【保单的扣费周期列表】 商户在与用户签约时,指定的若干个扣费周期。传空表示不更新,非空会用新列表覆盖旧列表。要求:扣费编号需要与创建签约的保持一致。
free_insurance 选填 boolean
【是否为赠险】 标识该保单是否为无需缴费的免费赠险。如更新为 false,需同步传入 payment_method 及相关缴费字段。
combined_payment 选填 boolean
【是否与其它保单合并扣费】 标识该保单的保费是否通过一笔合并支付订单缴纳(该订单同时支付了多张保单的保费),此时扣费金额可能和该保单的保费不一致,前端会做相应说明解释金额差异的原因。
payment_method 选填 string
【缴费方式】 保单的缴费方式。
可选取值
PAYMENT_METHOD_OTHER: 其它:即非期交、非趸交的其它缴费类型,无需传期交保费模式、缴费周期及保费金额字段PAYMENT_METHOD_PERIOD: 期交:分期缴纳保费PAYMENT_METHOD_LUMP_SUM: 趸交:一次性缴清全部保费
period_premium_mode 选填 string
【期交保费模式】 期交保单的保费规则类型,需与 payment_method 一起传入。
可选取值
PERIOD_PREMIUM_MODE_EQUAL: 均分保费:每期保费相同PERIOD_PREMIUM_MODE_FIRST_DIFF: 非均分保费(仅首期保费有差异):仅首期保费与后续各期不同,且后续各期金额相同PERIOD_PREMIUM_MODE_MULTI_DIFF: 非均分保费(多期不一致):存在首期以外的任意期保费金额不同,含第二期保费差异或多期保费不一致,如自然费率重疾险,无需传保费金额字段
payment_period 选填 string
【缴费周期】 期交保单的缴纳周期类型,需与 payment_method 一起传入。
可选取值
PAYMENT_PERIOD_DAY: 日缴PAYMENT_PERIOD_WEEK: 周缴PAYMENT_PERIOD_BIWEEKLY: 双周缴PAYMENT_PERIOD_MONTH: 月缴PAYMENT_PERIOD_QUARTER: 季缴PAYMENT_PERIOD_HALF_YEAR: 半年缴PAYMENT_PERIOD_YEAR: 年缴
first_period_amount 选填 integer
【首期保费金额】 单位:分。趸交时为一次性缴清金额,期交时为首期扣费金额。需与 payment_method 一起传入;期交时还需与 period_premium_mode 一起传入。
subsequent_period_amount 选填 integer
【后续每期保费金额】 第二期起的每期保费金额,单位:分。均分保费时与首期金额相同。需与 payment_method、period_premium_mode、first_period_amount 一起传入。
coverage_term_type 选填 string
【保障期限类型】 保单的期限类型,分为日期型(COVERAGE_TERM_TYPE_FIXED_DATE)与终身保障型(COVERAGE_TERM_TYPE_LIFETIME)两种。若不填则不更新。
可选取值
COVERAGE_TERM_TYPE_FIXED_DATE: 日期型COVERAGE_TERM_TYPE_LIFETIME: 终身保障型
请求示例
PATCH
应答参数
200 OK
out_insurance_no 必填 string(32)
【商户保险编号】 商户侧的保单唯一值,商户自定义字段,商户侧需保证该商户号下的唯一性。只能是数字、大小写字母的组合。字段作为整个保单管理流程的保单的唯一标识
insurance_name 必填 string(50)
【保险名称】 用户投保的保险名称,用于展示给用户
insured_name_list 必填 array[string(1024)]
【被保险人姓名列表】 被保险人姓名全称:单被保人时传入对应的姓名,多被保人时传入数组,最多允许传入11人;字段为密文,解密请参考如何使用API证书解密敏感字段。
insurance_company_code 必填 string(32)
【承保公司代码】 微信保单服务为承保保险公司分配的唯一标识。请通过保险公司代码-名称映射表获取保险公司代码与最新名称。
effective_time 必填 string(25)
【保单生效时间】 标识保单保障期的起始时刻,从该时刻起(含边界)保单处于保障中状态。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。
expired_time 必填 string(25)
【保单失效时间】 标识保单保障期的结束时刻,在该时刻之前(不含边界)保单处于保障中状态。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。必须满足:保单失效时间大于保单生效时间: expired_time > effective_time
coverage_detail 必填 string(1000)
【保障详情】 保单对应的保障责任及保额,最多支持传入1000个字符;微信前端展示时,若内容大于等于998个字符,将从第998位截断并在末尾展示英文省略号。可参考:房屋主体损失:100万元;室内装潢损失:10万元;室内财产损失:10万元;水暖管爆裂损失:1万元;室内财产盗抢损失:2万元。
support_renewal 必填 boolean
【是否支持续保】 标识该保单是否支持续保功能
start_renewal_time 选填 string(25)
【可续保开始时间】 标识续保窗口的起始时刻,从该时刻起(含边界)允许发起续保。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。必须满足:(1)支持续保(support_renewal=true)时必填 (2)位于保障期内:effective_time < start_renewal_time ≤ expired_time
end_renewal_time 选填 string(25)
【可续保结束时间】 标识续保窗口的结束时刻,在该时刻之前(不含边界)允许发起续保。遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。 示例:2025-05-20T13:29:35+08:00 表示北京时间2025年5月20日13点29分35秒。必须满足:(1)支持续保(support_renewal=true)时必填 (2)大于可续保开始时间: end_renewal_time > start_renewal_time (3)不晚于保障期结束时间后60天: end_renewal_time ≤ expired_time + 60天。
policy_type 必填 string
【保单类型】 保单类型
可选取值
POLICY_TYPE_OTHER: 其余险POLICY_TYPE_MEDICAL: 医疗险POLICY_TYPE_ACCIDENT: 意外险POLICY_TYPE_CRITICAL: 重疾险POLICY_TYPE_CAR: 车险POLICY_TYPE_LIFE: 人寿险POLICY_TYPE_PROPERTY: 家财险POLICY_TYPE_PET: 宠物险POLICY_TYPE_ANNUITY: 年金险
car_number 选填 string(10)
【车牌信息】 保单类型为车险(policy_type=POLICY_TYPE_CAR)时,返回
pet_name 选填 string(10)
【宠物名称】 保单类型为宠物险(policy_type=POLICY_TYPE_PET)时,如果有传入,则返回
address 选填 string(300)
【地址信息】 保单类型为家财险(policy_type=POLICY_TYPE_PROPERTY)时,如果有传入,则返回
policy_state 必填 string
【保单状态】 商户上传或更新的保单状态
可选取值
POLICY_STATE_ISSUING: 【出单中】正在进行出单操作,保险公司还未通过承保请求POLICY_STATE_APPROVED: 【已承保】保险公司已承保,保单处于保障待生效或保障中状态POLICY_STATE_DECLINED: 【拒保】保险公司拒绝承保或出单失败POLICY_STATE_INACTIVE: 【已失效】因各种问题,保单失效(用户退保、保单到期、欠费失效、理赔额度用尽等)
policy_code 选填 string(64)
【保司保单号】 保司承保后,为用户保单分配的唯一标识。保单状态为已承保、已失效时,返回。
plan_id 必填 string
【保险委托代扣模板ID】 是商户在微信支付保险委托代扣平台申请模板,得到的唯一标识。
out_contract_code 必填 string(32)
【商户签约协议号】 商户侧的签约协议号,商户自定义字段,商户侧需保证唯一性。只能是数字、大小写字母的组合。
policy_periods 选填 array[integer]
【保单的扣费周期列表】 商户在与用户签约时,指定的若干个扣费周期。要求:扣费编号需要与创建签约的保持一致。
free_insurance 选填 boolean
【是否为赠险】 标识该保单是否为无需缴费的免费赠险。
combined_payment 选填 boolean
【是否与其它保单合并扣费】 标识该保单的保费是否通过一笔合并支付订单缴纳(该订单同时支付了多张保单的保费),此时扣费金额可能和该保单的保费不一致,前端会做相应说明解释金额差异的原因。
payment_method 选填 string
【缴费方式】 保单的缴费方式。
可选取值
PAYMENT_METHOD_OTHER: 其它:即非期交、非趸交的其它缴费类型,无需传期交保费模式、缴费周期及保费金额字段PAYMENT_METHOD_PERIOD: 期交:分期缴纳保费PAYMENT_METHOD_LUMP_SUM: 趸交:一次性缴清全部保费
period_premium_mode 选填 string
【期交保费模式】 期交保单的保费规则类型。
可选取值
PERIOD_PREMIUM_MODE_EQUAL: 均分保费:每期保费相同PERIOD_PREMIUM_MODE_FIRST_DIFF: 非均分保费(仅首期保费有差异):仅首期保费与后续各期不同,且后续各期金额相同PERIOD_PREMIUM_MODE_MULTI_DIFF: 非均分保费(多期不一致):存在首期以外的任意期保费金额不同,含第二期保费差异或多期保费不一致,如自然费率重疾险,无需传保费金额字段
payment_period 选填 string
【缴费周期】 期交保单的缴纳周期类型。
可选取值
PAYMENT_PERIOD_DAY: 日缴PAYMENT_PERIOD_WEEK: 周缴PAYMENT_PERIOD_BIWEEKLY: 双周缴PAYMENT_PERIOD_MONTH: 月缴PAYMENT_PERIOD_QUARTER: 季缴PAYMENT_PERIOD_HALF_YEAR: 半年缴PAYMENT_PERIOD_YEAR: 年缴
first_period_amount 选填 integer
【首期保费金额】 单位:分。payment_method=PAYMENT_METHOD_LUMP_SUM(趸交)时为一次性缴清金额;payment_method=PAYMENT_METHOD_PERIOD(期交)时为首期扣费金额。
subsequent_period_amount 选填 integer
【后续每期保费金额】 payment_method=PAYMENT_METHOD_PERIOD(期交)且 period_premium_mode=PERIOD_PREMIUM_MODE_EQUAL(均分保费)或 period_premium_mode=PERIOD_PREMIUM_MODE_FIRST_DIFF(非均分保费(仅首期保费有差异))时返回。第二期起的每期保费金额,单位:分。如果是均分保费,则与首期金额相同。
coverage_term_type 选填 string
【保障期限类型】 保单的期限类型,分为日期型(COVERAGE_TERM_TYPE_FIXED_DATE)与终身保障型(COVERAGE_TERM_TYPE_LIFETIME)两种。
可选取值
COVERAGE_TERM_TYPE_FIXED_DATE: 日期型COVERAGE_TERM_TYPE_LIFETIME: 终身保障型
应答示例
200 OK
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
