小程序签约

更新时间：2025.03.21

商户后台通过请求此接口获取到签约会话id，然后再通过小程序签约接口唤起小程序委托代扣的签约页面。

注意：

小程序签约分为两个步骤，步骤1通过预签约接口获得session_id，再通过步骤2调起签约

步骤1：预签约API

1. 接口说明

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

请求URL：https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/miniprogram-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 签约用户的名称，用于页面展示,不需要对值进行urlencode，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段示例值：张三
签约成功通知url	success_notify_url	string[1, 256]	是	Body HTTPS开头的回调通知url ,不需要对值进行urlencode 示例值：https://yoursite.com
商户appid下的用户标识	openid	string[1, 128]	是	Body 用户在商户appid下的openid，服务商模式为子商户下的用户openid，可详见获取openid 示例值：ouFhd5X9s9WteC3eWRjXV3lea123
用户客户端IP	user_client_ip	string[1, 32]	否	Body 该字段要求填入用户客户端的IP，用户签约时会校验用户客户端IP与商户传的用户客户端IP一致，若不一致则视为商户引导的用户和实际访问用户不一致，会拒绝该签约请求。示例值：119.145.83.6
过期时间	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

请求示例

场景一：直连模式

1{
2	  "appid": "wxcbda96de0b165486",
3	  "expired_time": "2021-11-20T13:29:35+08:00",
4	  "openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
5	  "out_contract_code": "100001256",
6	  "plan_id": 123,
7	  "success_notify_url": "https://yoursite.com",
8	  "user_client_ip": "119.145.83.6",
9	  "user_display_name": "张三"
10}

场景二：服务商模式/机构模式

1{
2	  "expired_time": "2021-11-20T13:29:35+08:00",
3	  "openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
4	  "out_contract_code": "100001256",
5	  "plan_id": 123,
6	  "return_url": "https://yoursite.com",
7	  "sp_appid": "wxcbda96de0b165486",
8	  "sub_appid": "wxcbda96de0b165484",
9	  "sub_mchid": "10000097",
10	  "success_notify_url": "https://yoursite.com",
11	  "user_display_name": "张三"
12}

3. 返回参数

参数名	变量	类型[长度限制]	必填	描述
委托代扣签约会话id	session_id	string[1,128]	是	微信返回的委托代扣签约会话id 示例值：201710180325670965

返回示例

场景一：直连模式

1{
2  "session_id": "201710180325670965"
3}

4. 错误码

状态码	错误码	描述	解决方案
403	CONTRACT_EXISTED	已开通自动扣费服务功能，无需重复开通	已开通自动扣费服务功能，无需重复开通；如需重新签约，需解约后再发起签约
400	PARAM_ERROR	参数错误	传入正确查询参数
500	SYSTEM_ERROR	系统错误	请稍等重试

步骤2：小程序签约API

wx.navigateToMiniProgram

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

接口名称：wx.navigateToMiniProgram(OBJECT)接口，详见小程序API文档

接口说明：iOS 微信客户端 6.5.9 版本开始支持，Android 客户端在 6.5.10 版本开始支持

请求参数

参数名

变量

类型[长度限制]

必填

描述

微信签约小程序appid

appId

string[1,32]

是

固定值：wxbd687630cd02ce1d
请在小程序配置文件app.json的配置项navigateToMiniProgramAppIdList中增加此appid
示例值：wxbd687630cd02ce1d

场景信息传递给小程序的数据

extraData

object

是

Body 将详情见extraData字段详细说明

场景信息传递给小程序的数据

请求示例

示例代码

1wx.navigateToMiniProgram({
2	appId: wxbd687630cd02ce1d,
3	path: 'pages/Oversea/walletSelect?sessionId=201710180325670965',
4	extraData: {},
5	success(res) {
6		// 成功跳转到签约小程序
7	},
8	fail(res) {
9		// 未成功跳转到签约小程序
10	}
11})

返回参数

参数名	变量	类型[长度限制]	必填	描述
委托代扣协议id	contract_id	string(64)	是	签约成功后微信返回的委托代扣协议id 示例值：201710180325670965

返回示例

示例代码

1App({
2  onShow(res) {
3    if (res.scene === 1038) { // 场景值1038：从被打开的小程序返回
4       const { appId, extraData } = res.referrerInfo
5         if (appId == 'wxbd687630cd02ce1d') { // appId为wxbd687630cd02ce1d：从签约小程序跳转回来
6           if (typeof extraData == 'undefined'){
7               // TODO
8               // 客户端小程序不确定签约结果，需要向商户侧后台请求确定签约结果
9               return;
10                }
11                if(extraData.return_code == 'SUCCESS'){
12                    // TODO
13                    // 客户端小程序签约成功，需要向商户侧后台请求确认签约结果
14                    var contract_id = extraData.contract_id
15                    return;
16                } else {
17                    // TODO
18                    // 签约失败
19                    return;
20                }
21            }
22        }
23    }
24})