小程序签约API
最新更新时间：2021.08.15 版本说明
商户后台通过请求此接口获取到签约会话id，然后再通过小程序签约接口唤起小程序委托代扣的签约页面。
注意：
• 小程序签约分为两个步骤，步骤1通过预签约接口获得session_id，再通过步骤2调起签约
步骤1：预签约API
接口说明
适用对象：直连模式 机构模式
接口URL：https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/miniprogram-pre-entrust-sign
请求方式：POST
接口规则：https://wechatpay-api.gitbook.io/wechatpay-api-v3/
path 指该参数为路径参数
query 指该参数为URL参数
body 指该参数需在请求JSON传参
时序图
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 应用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] | 是 | bodyHTTPS开头的回调通知url ,不需要对值进行urlencode 示例值：https://yoursite.com |
| 商户appid下的用户标识 | openid | string[1, 128] | 是 | body用户在商户appid下的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 |
请求示例：
{
"appid": "wxcbda96de0b165486",
"expired_time": "2021-11-20T13:29:35+08:00",
"openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
"out_contract_code": "100001256",
"plan_id": 123,
"success_notify_url": "https://yoursite.com",
"user_client_ip": "119.145.83.6",
"user_display_name": "张三"
}返回参数
正常返回
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 委托代扣签约会话id | session_id | string[1, 128] | 是 | 微信返回的委托代扣签约会话id 示例值：201710180325670965 |
返回示例：
{
"session_id": "201710180325670965"
}
步骤2：小程序签约API
wx.navigateToMiniProgram
适用对象：直连模式 机构模式
接口名称：wx.navigateToMiniProgram(OBJECT)接口，详见小程序API文档
接口说明：iOS 微信客户端 6.5.9 版本开始支持，Android 客户端在 6.5.10 版本开始支持
请求参数
Object object
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信签约小程序appid | appId | string[1,32] | 是 | 固定值：wxbd687630cd02ce1d 请在小程序配置文件app.json的配置项navigateToMiniProgramAppIdList中增加此appid 示例值：wxbd687630cd02ce1d |
| +场景信息传递给小程序的数据 | extraData | object | 是 | 将详情见extraData字段详细说明 |
| 打开小程序的页面路径 | path | string[1,32] | 是 | 页面为固定值pages/Oversea/walletSelect，可在路径中携带参数 示例值：pages/Oversea/walletSelect?sessionId=201710180325670965 |
| 接口调用成功的回调函数 | success | function | 是 | 接口调用成功的回调函数 |
| 接口调用失败的回调函数 | fail | function | 是 | 接口调用失败的回调函数 |
| 接口调用结束的回调函数 | complete | function | 是 | 调用成功、失败都会执行 |
请求示例
wx.navigateToMiniProgram({
appId: wxbd687630cd02ce1d,
path: 'pages/Oversea/walletSelect?sessionId=201710180325670965',
extraData: {},
success(res) {
// 成功跳转到签约小程序
},
fail(res) {
// 未成功跳转到签约小程序
}
})
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 委托代扣协议id | contract_id | string(64) | 是 | 签约成功后微信返回的委托代扣协议id 示例值：201710180325670965 |
返回示例
App({
onShow(res) {
if (res.scene === 1038) { // 场景值1038：从被打开的小程序返回
const { appId, extraData } = res.referrerInfo
if (appId == 'wxbd687630cd02ce1d') { // appId为wxbd687630cd02ce1d：从签约小程序跳转回来
if (typeof extraData == 'undefined'){
// TODO
// 客户端小程序不确定签约结果，需要向商户侧后台请求确定签约结果
return;
}
if(extraData.return_code == 'SUCCESS'){
// TODO
// 客户端小程序签约成功，需要向商户侧后台请求确认签约结果
var contract_id = extraData.contract_id
return;
} else {
// TODO
// 签约失败
return;
}
}
}
}
})
