WEB预签约API
最新更新时间：2021.12.08 版本说明
该方式适用于PC等使用浏览器的设备场景使用微信签约扣款。商户在网站后端通过微信支付WEB签约接口获取到签约链接，在网站前端将签约链接生成二维码，引导用户扫码识别该链接，用户访问该链接进入代扣签约页面；用户签约完成后留在微信。WEB 端等待签约回调通知，或者定时轮询查询用户签约状态，更新页面内容。
1. 接口说明
适用对象： 直连模式 机构模式
请求URL：https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/web-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 |
| 过期时间 | expired_time | string[1, 64] | 否 | 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 |
请求示例
{
"appid": "wxcbda96de0b165486",
"expired_time": "2021-11-20T13:29:35+08:00",
"out_contract_code": "100001256",
"plan_id": 123,
"success_notify_url": "https://yoursite.com",
"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 | 系统错误 | 请稍等重试 |
页面导航
