普通服务商H5场景预约扣费类型签约的预签约API

更新时间：2024.11.18

接口说明

商户可调用本接口预先指定签约信息，生成预签约会话及对应的跳转URL，引导用户在原浏览器中请求该URL，将跳转至用户微信支付客户端的签约页面。用户可在微信支付客户端内完成签约流程；

若用户同意本次流程，则微信支付会通过商户指定的回调地址通知签约结果；若用户未同意或者流程执行失败，则不通知签约结果。

商户签约协议号在进行签约后不能在重复使用，包括用户确认签约后因业务规则限制没有完成签约的协议、签约成功后已经解约的协议及签约成功生效中的协议。商户可通过查询协议接口确认商户侧协议号是否已经使用。

注意：商户获取的签约会话有效期为10分钟。

特别提醒：H5纯签约接口暂未对外开放，如有需要请咨询对应行业运营，或参考接入前准备，额外申请开通。

跳转说明

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只有域名没有路径，那么签约完成后，需要用户手动回到浏览器。

接口说明

支持商户：【普通服务商】

请求方式：【POST】/v3/papay/scheduled-deduct-sign/partner/contracts/pre-entrust-sign/h5

请求域名：【主域名】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

body 包体参数

sp_appid 　必填 string(32)

【应用ID】商户在微信申请的公众号或移动应用AppID

sp_openid 　选填 string(64)

【用户在服务商商户应用下的用户标示】JSAPI和小程序场景签约必须和'sp_openid'二选一填写，对应的用户需与实际在微信客户端中进行签约的用户一致。

sub_mchid 　必填 string(32)

【子商户号】微信支付分配的商户号

sub_appid 　选填 string(32)

【子商户的AppID】AppID是商户在微信申请公众号或移动应用成功后分配的账号ID，登录平台为mp.weixin.qq.com或open.weixin.qq.com

sub_openid 　选填 string(64)

【子商户AppID对应的用户OpenID】商户AppID下的用户唯一标识，对应的用户需与实际在微信客户端中进行签约的用户一致。

plan_id 　必填 integer

【委托代扣模板ID】委托代扣模板ID，申请见接入指引中的接入流程相关内容。

out_contract_code 　必填 string(32)

【商户签约协议号】商户侧的签约协议号，商户侧需保证唯一性。只能是数字、大小写字母的组合

contract_display_account 　必填 string(32)

【用户账户展示名称】签约用户的名称，用于页面展示，在签约时由商户传入。

contract_notify_url 　必填 string(256)

【签约结果通知地址】接收微信支付异步通知回调地址，通知URL必须为HTTPS且可直接可访问的URL，不能携带参数。

out_user_code 　选填 string(32)

【商户侧用户标识】在多账号签约场景下使用。一个用户微信账号可能会在商户系统中存在多个账号，并开通多个签约协议。商户可以使用商户侧用户标识区分商户系统中的不同用户账号。注：使用多账号签约规则时，微信支付系统将限制相同的商户侧用户标识只能与同一个委托代扣模板签署一份生效中的协议。

deduct_schedule 　选填 object

【用于预约扣费的预约信息】用于预约扣费的预约信息，在使用预约扣费类型的模板进行预签约时，该值必填。

属性

estimated_deduct_date 　必填 string(32)

【预计扣费的日期】预约扣费场景下有效，预计扣费的日期，若预签约时间小于19:00，预计扣费日期必须晚于签约日期至少一个自然日，若预签约时间大于19：00，预计扣费日期必须晚于签约日期至少两个自然日。遵循rfc3339标准格式，格式为yyyy-MM-DD，yyyy-MM-DD表示年月日，例如：2015-05-20表示，北京时间2015年5月20日。

estimated_deduct_amount 　必填 object

【预计的扣费金额】预约扣费场景下有效，预计的扣费金额。

属性

total 　必填 integer

【金额】总金额，单位为分，只能为整数。

currency 　选填 string

【货币类型】枚举类型，符合ISO 4217标准的三位字母代码，默认为CNY，目前只支持CNY。

可选取值：

CNY: 扣费货币类型-人民币

description 　必填 string(32)

【商品描述】用户进行预约扣费购买的商品描述，将展示给用户

jump_control 　选填 object

【跳转控制信息】目前仅在H5签约场景生效。指定相关参数，可控制签约完成后跳转的路径。

属性

jump_appid 　选填 string

【跳转的应用AppID】仅H5签约场景生效。当商户已经申请H5签约完成后返回App的权限且指定跳转的应用AppID，签约完成后将返回该AppID对应的App应用。如果不填且签约发起时的来源UA可被微信识别，则跳转到UA对应的App应用，否则留在微信。识别UA并进行跳转的功能仅需绑定UA与回跳应用关系，无需申请跳转权限。申请跳转权限、绑定AppID与回跳应用关系、绑定UA与回跳应用关系的流程可参考指引文档中的接入前准备部分。

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/papay/scheduled-deduct-sign/partner/contracts/pre-entrust-sign/h5 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "sp_appid" : "wxd678efh567hg6787",
8    "sp_openid" : "oYobu0MVnQfWpSMOYJz2AHPG_gQw",
9    "sub_mchid" : "1900000109",
10    "sub_appid" : "wxd678efh567hg6787",
11    "sub_openid" : "wxd678efh567hg6787",
12    "plan_id" : 12535,
13    "out_contract_code" : "wxwtdk20200910100000",
14    "contract_display_account" : "微信代扣用户A",
15    "contract_notify_url" : "https://yourapp.com/notify",
16    "out_user_code" : "用户A",
17    "deduct_schedule" : {
18      "estimated_deduct_date" : "2019-11-22",
19      "estimated_deduct_amount" : {
20        "total" : 1,
21        "currency" : "CNY"
22      },
23      "description" : "小乔-碎云皮肤（微信83区沧海之耀）"
24    },
25    "jump_control" : {
26      "jump_appid" : "wxd678efh567hg6787"
27    }
28  }'
29

应答参数

200 OK

redirect_url 　必填 string(512)

【拉起微信支付客户端的URL】用于浏览器拉起微信支付客户端签约页面的URL

应答示例

200 OK

1{
2  "redirect_url" : "https://www.xxx.com/xxxtemplate?session_id=wx12334"
3}
4

错误码

公共错误码

状态码	错误码	描述	解决方案
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	接口返回错误	系统异常，请用相同参数重新调用

文档是否有帮助

LLM请查看llms.txt

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服

普通服务商H5场景预约扣费类型签约的预签约API

接口说明

跳转说明

接口说明

请求参数 折叠全部参数

应答参数

错误码

公共错误码

业务错误码

请求参数
折叠全部参数