代扣预签约

更新时间：2024.12.20

接口说明

支持商户：【普通商户】

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

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

sign_scene 　必填 string

【签约场景】签约场景，预签约时设置的签约场景要与用户实际签约场景一致。

可选取值

SIGN_SCENE_APP: APP签约
SIGN_SCENE_QRCODE: 扫码签约

appid 　必填 string(32)

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

openid 　选填 string(128)

【用户在直连商户应用下的用户标示】对应的用户需与实际在微信客户端中进行签约的用户一致。

plan_id 　必填 integer

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

out_contract_code 　必填 string(32)

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

contract_display_account 　必填 string(32)

【用户账户展示名称】微信代扣用户A

contract_notify_url 　必填 string(256)

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

out_user_code 　必填 string(64)

【商户侧用户标识】用户A

device_info 　必填 object

【发起预签约的用户，其设备信息】

属性

device_type 　必填 string

【设备类型】发起预签约时，用户的设备类型。

可选取值

DEVICE_TYPE_UNKNOW: 设备类型未知
DEVICE_TYPE_PHONE: 手机
DEVICE_TYPE_PAD: 平板
DEVICE_TYPE_TV: 电视
DEVICE_TYPE_WATCH: 手表

device_os 　必填 string(128)

【设备的OS版本】发起预签约时，用户的设备上OS的版本。

device_id 　必填 string(128)

【设备ID】发起预签约时，用户设备的ID。

device_running_as_root 　必填 boolean

【设备是否以root身份运行】发起预签约时，用户设备是否以root身份运行。

device_ip 　必填 string(64)

【设备的IP】发起预签约时，用户设备的IP，兼容IPV4和IPV6。

weixin_installed 　必填 boolean

【设备上是否安装微信】发起预签约时，用户设备上是否安装微信。

weixin_version 　必填 string(64)

【设备上微信的版本】发起预签约时，用户设备上如果安装微信，需传入微信的版本。

days_since_first_login 　必填 string

【发起预签约的用户首次登录该设备的时间】发起预签约时，用户在该设备的首次登录时间距离今天多久。

可选取值

DAYS_SINCE_FIRST_LOGIN_UNKNOW: 距离现在的天数未知
DAYS_SINCE_FIRST_LOGIN_WITHIN_1_DAY: 距离现在(0,1]天
DAYS_SINCE_FIRST_LOGIN_WITHIN_7_DAYS: 距离现在(1,7]天
DAYS_SINCE_FIRST_LOGIN_WITHIN_30_DAYS: 距离现在(7,30]天
DAYS_SINCE_FIRST_LOGIN_WITHIN_90_DAYS: 距离现在(30,90]天
DAYS_SINCE_FIRST_LOGIN_WITHIN_180_DAYS: 距离现在(90,180]天
DAYS_SINCE_FIRST_LOGIN_MORE_THEN_180_DAYS: 距离现在大于180天

return_url 　选填 string(256)

【回跳地址的url】在扫码签约成功后，回跳地址的url。

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/papay/sign/contracts/pre-entrust-sign \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "sign_scene" : "SIGN_SCENE_APP",
8    "appid" : "wxd678efh567hg6787",
9    "openid" : "oYobu0MVnQfWpSMOYJz2AHPG_gQw",
10    "plan_id" : 12345,
11    "out_contract_code" : "wxwtdk20200910100000",
12    "contract_display_account" : "example_contract_display_account",
13    "contract_notify_url" : "https://yourapp.com/notify",
14    "out_user_code" : "example_out_user_code",
15    "device_info" : {
16      "device_type" : "DEVICE_TYPE_UNKNOW",
17      "device_os" : "example_device_os",
18      "device_id" : "example_device_id",
19      "device_running_as_root" : false,
20      "device_ip" : "example_device_ip",
21      "weixin_installed" : false,
22      "weixin_version" : "example_weixin_version",
23      "days_since_first_login" : "DAYS_SINCE_FIRST_LOGIN_UNKNOW"
24    },
25    "return_url" : "example_return_url"
26  }'
27

应答参数

200 OK

pre_entrustweb_id 　必填 string(128)

【预签约ID】委托代扣签约会话ID，十分钟内有效，用于跳转签约流程的传入参数。

mini_program_username 　选填 string(32)

【跳转签约小程序的username】 APP签约时，进行跳转签约流程的传入参数。

mini_program_path 　选填 string(256)

【跳转签约小程序的path】 APP签约时，进行跳转签约流程的传入参数。

redirect_url 　选填 string(4096)

【展示扫码签约的二维码的URL】用于浏览器拉起微信支付客户端签约页面的URL。

应答示例

200 OK

1{
2  "pre_entrustweb_id" : "5778aadY9nltAsZzXixCkFIGYnV2V",
3  "mini_program_username" : "example_mini_program_username",
4  "mini_program_path" : "example_mini_program_path",
5  "redirect_url" : "example_redirect_url"
6}
7

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

文档是否有帮助

更多支持

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