Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

H5预签约API

最新更新时间:2024.03.18 版本说明

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

注意:

• 商户上送敏感信息时使用微信支付平台公钥加密,证书序列号包含在请求HTTP头部的Wechatpay-Serial,详见接口规则

1. 接口说明

适用对象: 直连模式 机构模式

请求URL:https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/h5-pre-entrust-sign

请求方式:POST


Path指该参数为路径参数
Query指该参数为URL参数
Body指该参数需在请求JSON传参

时序图


2. 请求参数

参数名 变量 类型[长度限制] 必填 描述
应用ID appid string[1, 32] Body商户号绑定的AppID
注意:仅适用于直连模式
示例值:wxcbda96de0b165486
子商户号 sub_mchid string[1, 32] Body微信支付分配的子商户号
注意:仅适用于机构模式
示例值:10000097
服务商应用ID sp_appid string[1, 32] Body服务商绑定的AppID
注意:仅适用于机构模式
示例值:wxcbda96de0b165486
子商户应用ID sub_appid string[1, 32] Body发起签约的子商户号绑定的AppID
注意:仅适用于机构模式
示例值:wxcbda96de0b165484
模板ID plan_id int Body协议模板ID,该模板ID是商户在向微信支付提交代扣权限申请时由微信支付生成
示例值:123
商户侧签约协议号 out_contract_code string[1, 32] Body商户请求签约时传入的签约协议号,商户侧须唯一
示例值:100001256
用户账户展示名称 user_display_name string[1, 32] Body签约用户的名称,用于页面展示,不需要对值进行URL编码,参数值不支持UTF8非3字节编码的字符,例如表情符号,所以请勿传微信昵称到该字段
示例值:张三
签约成功通知URL success_notify_url string[1, 256] BodyHTTPS开头的回调通知URL ,不需要对值进行URL编码
示例值:https://yoursite.com
回调应用AppID return_appid string[1, 32] Body用来控制签约页面结束后的返回路径。 当指定该字段时,且商户模板标注商户具有指定返回app的权限时,签约成功将返回return_appid指定的app应用,如果不填且签约发起时的浏览器UA可被微信识别,则跳转到浏览器,否则留在微信
示例值:wxcbda96de0b165486
用户客户端IP user_client_ip string[1, 32] Body该字段要求填入用户客户端的IP,用户签约时会校验用户客户端IP与商户传的用户客户端IP一致,若不一致则视为商户引导的用户和实际访问用户不一致,会拒绝该签约请求。
示例值:119.145.83.6
过期时间 expired_time string[1, 32] Body境外代扣签约会话ID过期时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2021-11-20T13:29:35+08:00表示,北京时间2021年11月20日 13点29分35秒。
示例值:2021-11-20T13:29:35+08:00
签约完成跳转URL return_url string[1, 256] Body用来控制签约页面结束后的返回路径(不传此参数,则签约完成后停留在微信内)。非空时,URL路径前缀需在申请模板时提供给微信支付运营人员配置,未配置或者前缀不匹配则不跳转
示例值:https://yoursite.com

请求示例

{
	  "appid": "wxcbda96de0b165486",
	  "expired_time": "2021-11-20T13:29:35+08:00",
	  "out_contract_code": "100001256",
	  "plan_id": 123,
	  "return_appid": "wxcbda96de0b165486",
	  "return_url": "https://yoursite.com",
	  "success_notify_url": "https://yoursite.com",
	  "user_client_ip": "119.145.83.6",
	  "user_display_name": "张三"
}
{
	  "expired_time": "2021-11-20T13:29:35+08:00",
	  "out_contract_code": "100001256",
	  "plan_id": 123,
	  "return_appid": "wxcbda96de0b165486",
	  "return_url": "https://yoursite.com",
	  "sp_appid": "wxcbda96de0b165486",
	  "sub_appid": "wxcbda96de0b165484",
	  "sub_mchid": "10000097",
	  "success_notify_url": "https://yoursite.com",
	  "user_client_ip": "119.145.83.6",
	  "user_display_name": "张三"
}

3. 返回参数

参数名 变量 类型[长度限制] 必填 描述
签约跳转URL sign_url string[1,512] 有效期为10分钟,跳转签约页面URL,用户通过跳转访问此URL即可进入微信签约页面,进行签约。签约完成后,按照 return_appid 的描述跳转回对应的应用
示例值:https://apihk.mch.weixin.qq.com/global/papay/contracts/login?os_session_id=2021120910391616228#wechat_redirect

返回示例

{
  	"sign_url": "https://apihk.mch.weixin.qq.com/global/papay/contracts/login?os_session_id=2021120910391616228#wechat_redirect"
}

4. 错误码

状态码 错误码 描述 解决方案
403 CONTRACT_NOT_EXIST Result Empty 查询的签约协议不存在,或者传入正确查询参数重试
403 CONTRACT_EXISTED 已开通自动扣费服务功能,无需重复开通 已开通自动扣费服务功能,无需重复开通;如需重新签约,需解约后再发起签约
400 PARAM_ERROR 参数错误 传入正确查询参数
500 SYSTEM_ERROR 系统错误 请稍等重试


    页面导航

版本说明

关闭
V1.0
2021年12月8日
1. H5预签约接口上线

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

置顶