H5纯签约

更新时间：2024.11.14

该方式适用于手机、平板电脑等使用H5浏览器的设备场景使用微信签约扣款。商户在网站前端通过微信支付H5纯签约接口与用户签订委托扣款协议，再通过后台接口申请扣款来完成代扣交易。

注意：

如果签约成功，微信会异步通知给商户（notify_url为通知路径），如果签约失败则不通知。

调用此接口后获得redirect_url，需要在前端跳转到redirect_url，在商户的前端页面<head>处需要添加声明<meta name="referrer" content="no-referrer-when-downgrade">

此外，不能使用window.location.replace(redirect_url)的方式跳转，而要通过window.location.href = redirect_url的方式跳转。

在redirect_url页面，会唤起微信。无论用户是否同意，redirect_url的页面会在3秒后自动回到refer页面。

如果获取的refer只有域名没有路径，那么签约完成后，需要用户手动回到浏览器。

特别提醒：H5纯签约接口暂未对外开放，如有需要请咨询对接的业务人员，额外申请开通。

接口说明

适用对象：服务商

请求URL： https://api.mch.weixin.qq.com/papay/partner/h5entrustweb

请求方式： GET

签名方式： HMAC-SHA256、MD5

是否需要证书：否

请求参数

参数名	变量	类型[长度限制]	必填	描述
应用ID	appid	string[1,32]	是	服务商申请的公众号或移动应用appid。示例值：wxcbda96de0b165486
商户号	mch_id	string[1,32]	是	商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com 示例值：1200009811
子商户应用ID	sub_appid	string[1,32]	否	子商户号绑定的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定) 示例值：wxcbda96de0b165489
子商户号	sub_mch_id	string[1,32]	是	微信支付分配的子商户号示例值：1900000109
模板id	plan_id	string[1,28]	是	协议模板id，设置路径见开发步骤。示例值：12535
签约协议号	contract_code	string[1,128]	是	商户侧的签约协议号，由商户生成，只能是数字、大小写字母的描述。示例值：100000
请求序列号	request_serial	int64	是	商户请求签约时的序列号，要求唯一性。禁止使用0开头，序列号主要用于排序，不作为查询条件，纯数字,范围不能超过int64的范围（9223372036854775807）。示例值：1000
用户账户展示名称	contract_display_account	string[1,128]	是	签约用户的名称，用于页面展示，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段示例值：微信代扣
回调通知url	notify_url	string[1,256]	是	用于接收签约成功消息的回调通知地址，以http或https开头，通知url必须为外网可访问的url，不能携带参数。请对notify_url参数值进行encode处理,注意是对参数值进行encode，例如参数为notify_url=“https://weixin.qq.com”，则需要encode的内容为https://weixin.qq.com。示例值：https://weixin.qq.com
版本号	version	string[1,8]	是	固定值1.0 示例值：1.0
签名	sign	string[1,64]	是	详见签名生成算法示例值：C380BEC2BFD727A4B6845133519F3AD6
签名类型	sign_type	string[1,32]	否	MD5或者HMAC-SHA256，不填默认HMAC-SHA256 注意：H5的预签约的默认签名方式是(sign_type为空或无该字段)：HMAC-SHA256 示例值：MD5
时间戳	timestamp	string[1,10]	是	系统当前时间，10位示例值：1414488825
客户端 IP	clientip	string[1,32]	是	用户客户端的IP地址示例值：119.145.83.6
设备ID	deviceid	string[1,32]	否	android填imei的一次md5; ios填idfa的一次md5 非必填，风控参数，建议商户填写，提高风险控制能力示例值：baf04e6bbbd06f7b1a197d18ed53b7f1
手机号	mobile	string[1,11]	否	用户手机号非必填，风控参数，建议商户填写，提高风险控制能力示例值：18933432355
邮箱地址	email	string[1,]	否	用户邮箱地址非必填，风控参数，建议商户填写，提高风险控制能力示例值：aobama@whitehouse.com
QQ号	qq	string[1,]	否	用户QQ号非必填，风控参数，建议商户填写，提高风险控制能力示例值：100243
微信openID	openid	string[1,128]	否	用户微信open ID 非必填，风控参数，建议商户填写，提高风险控制能力示例值：baf04e6bbbd06f7b1a197d18ed53b7f1
身份证号	creid	string[1,]	否	用户身份证号非必填，风控参数，建议商户填写，提高风险控制能力示例值：110102199701011000
商户侧用户标识	outerid	string[1,]	否	用户在商户侧的标识非必填，风控参数，建议商户填写，提高风险控制能力示例值：user123
回调应用appid	return_appid	string[1,32]	否	用来控制签约页面结束后的返回路径。当指定该字段时，且商户模板标注商户具有指定返回app的权限时，签约成功将返回return_appid指定的app应用，如果不填且签约发起时的浏览器UA可被微信识别，则跳转到浏览器，否则留在微信示例值：wxcbda96de0b165486

请求示例：

URL

1https://api.mch.weixin.qq.com/papay/partner/h5entrustweb?appid=wx426a3015555a46be&contract_code=122&contract_display_account=name1&mch_id=1223816102&sub_mch_id=1223816103¬ify_url=www.qq.com%2Ftest%2Fpapay&plan_id=106&request_serial=123&return_appid=wxcbda96de0b165542&clientip=12.1.1.12×tamp=1414488825&version=1.0&sign=130C7B07DD3B8074F7BF8BEF5C9A86487A1C57478F8C55587876B9C782F72036

返回参数

参数名	变量	类型[长度限制]	必填	描述
返回状态码	return_code	string[1,16]	是	SUCCESS/FAIL 非签约结果标识，签约发起是否成功需要查看result_code来判断。示例值：SUCCESS
返回信息	return_msg	string[1,128]	否	返回信息，如非空，为错误原因如：签名失败等。示例值：签名失败

以下字段在return_code为SUCCESS的时候有返回

参数名	变量	类型[长度限制]	必填	描述
业务结果	result_code	string[1,16]	是	SUCCESS/FAIL 示例值：SUCCESS
业务结果描述	result_msg	string[1,32]	否	如非空，为错误原因，如签名错误示例值：SIGN_ERROR
跳转URL	redirect_url	string[1,256]	否	跳转签约页面url，用户通过跳转访问此URL即可进入微信签约页面，进行签约。注意这里请求跳转url的页面地址必须在微信后台配置（申请H5签约权限时配置）。示例值：https://payapp.weixin.qq.com

返回示例：

正常示例

1<xml>
2 <return_code><![CDATA[SUCCESS]]></return_code>
3 <return_msg><![CDATA[PARAM_ERROR]]></return_msg>
4 <result_code><![CDATA[SUCCESS]]></result_code>
5 <result_msg><![CDATA[SIGN_ERROR]]></result_msg>
6 <redirect_url><![CDATA[https://payapp.weixin.qq.com]]></redirect_url>
7</xml>

文档是否有帮助

更多支持

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