保险商户H5预签约API
更新时间：2024.11.12# 接口说明
商户可调用本接口预先指定签约及交易信息（交易信息可选填），生成预签约会话及对应的跳转URL，引导用户在原浏览器中请求该URL，将跳转至用户微信支付客户端的签约页面。若涉及敏感信息的传输，可参考【开发指引 (opens new window)】。
若商户指定交易信息，用户可在微信支付客户端内的完成签约和首期自动续费流程，即进行签约中支付 ；若未指定交易信息，用户可在微信支付客户端内完成签约流程，即进行纯签约；若用户同意本次流程，则微信支付会分别通过商户指定的回调地址通知签约结果和支付结果（如有指定交易信息）；若用户未同意或者流程执行失败，则不通知签约及交易结果（如有指定交易信息）。
商户签约协议号和商户订单号在进行签约后不能在重复使用，包括用户确认签约后没有完成支付导致签约失败的协议、签约成功后已经解约的协议及签约成功生效中的协议。商户可通过查询协议接口确认商户签约协议号是否已经使用。
注意：商户获取的签约会话有效期为10分钟。
特别提醒：H5纯签约接口暂未对外开放，如有需要请咨询对应行业运营，或参考接入前准备 (opens new window)，额外申请开通。
# 跳转说明
1、商户在完成预签约后获得redirect_url，需要在前端跳转到redirect_url，在商户的前端页面处需要添加声明<meta name="referrer" content="no-referrer-when-downgrade">
2、此外，不能使用window.location.replace(redirect_url)的方式跳转，而要通过window.location.href = redirect_url的方式跳转。
3、跳转到redirect_url页面后会唤起微信，并在3秒后自动回到referrer页面。
4、如果在微信支付的redirect_url页面获取的referrer只有域名没有路径，那么签约完成后，需要用户手动回到浏览器。
# 接口说明
# 请求参数
- appid 必填【应用ID】 商户在微信申请的公众号或移动应用AppID
- openid 选填【用户在直连商户应用下的用户标示】 JSAPI和小程序签约必填，对应的用户需与实际在微信客户端中进行签约的用户一致。OpenID获取详见
- plan_id 必填【委托代扣模板ID】 委托代扣模板ID，申请见接入指引中的接入流程相关内容。
- out_contract_code 必填【商户签约协议号】 商户侧的签约协议号，商户侧需保证唯一性。只能是数字、大小写字母的组合
- insured_display_name 必填【被保人的展示名称】 保险被保人的姓名掩码，由商户传入，用于在签约页面展示。如为个人保单，则只保留最后一个字符，除最后一个字符外全部字符（包括“.”等符号）均使用替代；如姓名长度大于4个字符，统一用3个“”+1位明文展示，如***G，如为家庭或者团体保单，传入的格式为“多人保单-**明等”。固定前缀为“多人保单-”，后面为投保人代表的姓名掩码及“等”字
- contract_notify_url 必填【签约结果通知地址】 接收微信支付异步通知回调地址，通知URL必须为HTTPS且可直接可访问的URL，不能携带参数。
- policy_start_date 必填【保险保单的开始日期】 保险保单的开始日期 ，遵循rfc3339标准格式，格式为yyyy-MM-DD，yyyy-MM-DD表示年月日，例如：2015-05-20表示，北京时间2015年5月20日。
- policy_end_date 必填【保险保单的结束日期】 保险保单的结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DD，yyyy-MM-DD表示年月日，例如：2015-05-20表示，北京时间2015年5月20日。
- policy_periods 必填【保单的扣费周期列表】 商户在与用户签约时，指定的若干个扣费周期，最多支持360个。进行纯签约或者支持自动重新投保/自动续保的签约中支付场景，至少传入1个扣费周期。不支持自动重新投保/自动续保的签约中支付场景，至少传入2个扣费周期。后续需要按照周期中的预计扣款时间和预计扣款金额进行预约扣款和扣款。预计扣款时间需要随着编号的递增而递增，编号较大的预计扣款时间不能早于编号较小的预计扣款时间。相邻编号的预计扣费时间间隔需要匹配委托代扣模板ID指定的扣费频率。若商户希望在进行签约后立即进行首期自动续费，首期的预计扣费日期必须等于调用本接口的日期，首期的预计扣费金额必须等于调用本接口的扣费金额信息。
- 属性
- amount 选填【扣费金额信息】 若商户希望在进行签约后立即进行首期自动续费，必须传入扣费金额信息，必须等于首个扣费周期的的预约金额。
- 属性
- out_trade_no 选填【商户订单号】 若商户希望在进行签约后立即进行首期自动续费，必须传入商户系统内部订单号。只能是数字、大小写字母且在同一个商户号下唯一
- description 选填【商品描述】 若商户希望在进行签约后立即进行首期自动续费，必须传入商品描述。
- transaction_notify_url 选填【支付结果通知地址】 若商户希望在进行签约后立即进行首期自动续费，必须传入异步接收微信支付结果通知的回调地址，通知URL必须为外网可访问的URL，不能携带参数。 公网域名必须为HTTPS，如果是走专线接入，使用专线NAT IP或者私有回调域名可使用HTTP
- out_user_code 选填【商户侧用户标识】 在多账号签约场景下使用。一个用户微信账号可能会在商户系统中存在多个账号，并开通多个签约协议。商户可以使用商户侧用户标识区分商户系统中的不同用户账号。注：使用多账号签约规则时，微信支付系统将限制相同的商户侧用户标识只能与同一个委托代扣模板签署一份生效中的协议。一个用户的微信账号在同一个模版下最多签约10份协议。
- goods_tag 选填【订单优惠标记】 在进行首期自动续费时，可选择使用优惠能力，传入在订单优惠标记。
- attach 选填【附加数据】 在进行首期自动续费时，可选择传入附加数据，在查询交易结果API和支付通知中原样返回，可作为自定义参数使用
- can_auto_insure 选填【是否自动续保】 指扣费计划到期后，商家按照最新费率为用户续保，续保保证成功，成功后沿用旧保单号。是否自动续保与是否自动重新投保不能同时设置。
- can_auto_reinsure 选填【是否自动重新投保】 指扣费计划到期后，商家按照最新费率为用户重新投保，不保证投保成功，投保成功后将生成新的保单号。是否自动续保与是否自动重新投保不能同时设置。
- real_identity 选填【用户实名信息】 商家可选择指定用户实名信息。指定用户实名信息后，微信支付系统会校验商户指定的用户实名信息跟用户在微信支付侧的实名信息是否一致。信息一致时才可进行签约，若信息不一致，不能进行本次签约。注：因实名信息不一致导致无法进行签约，微信支付将不会通知签约结果，也不会产生协议或订单信息。
- 属性
- jump_control 选填【跳转控制信息】 目前仅在H5签约场景生效。指定相关参数，可控制签约完成后跳转的路径。
- 属性
- combined_deduct_period_count 选填【合并扣费期数】 选填；首期合并扣费才填充；当前只支持2或3
请求示例
# 应答参数
- redirect_url 必填【拉起微信支付客户端的URL】 用于浏览器拉起微信支付客户端签约页面的URL
应答示例
# 错误码
# 公共错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
| 401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
| 500 | SYSTEM_ERROR | 系统异常，请稍后重试 | 请稍后重试 |
# 业务错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 无效请求 | 请根据接口返回的详细信息检查您的程序 |
| 403 | NO_AUTH | 商户暂无权限使用此功能 | 请开通商户号权限。请联系产品或商务申请 |
| 429 | FREQUENCY_LIMITED | 频率超限 | 请降低请求接口频率 |
| 500 | SYSTEM_ERROR | 接口返回错误 | 系统异常，请用相同参数重新调用 |
