---
url: "https://pay.weixin.qq.com/doc/v2/merchant/4011987274.md"
title: "小程序纯签约"
doc_id: 4011987274
---

>更新时间：2026.01.20

商户可以通过请求此接口唤起小程序委托代扣的签约页面

注意：

- 用户在微信的页面中完成代扣签约后，微信会同时将签约信息通过异步通知的方式通知给商户后台。如果用户放弃签约或签约失败则不通知。


商户流程介绍：

1.用户从商户小程序发起签约请求 (商户需确认委托代扣权限已开通，模板已审批通过，小程序APPID与商户号已绑定)。

2.商户将签约请求参数按照规则拼接之后，通过小程序跳转，向签约小程序发起签约请求。

3.用户在微信签约小程序选择支付方式完成签约。

4.微信将签约结果返回给商户。



## 接口说明

适用对象：直连商户

请求URL： wx.navigateToMiniProgram(OBJECT)接口

接口兼容： iOS 微信客户端 6.5.9 版本开始支持，Android 客户端即将在 6.5.10 版本开始支持

## OBJECT参数说明

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| :-- | :-- | :-- | :-- | :-- |
| 微信签约小程序appid | appId | string\[1,32\] | 是 | 固定值 ：wxbd687630cd02ce1d<br>请在小程序配置文件app.json的配置项navigateToMiniProgramAppIdList中增加此appid<br>示例值：wxbd687630cd02ce1d |
| 场景信息传递给小程序的数据 | extraData | object | 是 | 签约的请求参数，详情见extraData字段详细说明。 |
| 应用ID | appid | string\[1,32\] | 是 | 直连商户申请的公众号或移动应用appid。<br>示例值：wxcbda96de0b165486 |
| 商户号 | mch\_id | string\[1,32\] | 是 | 商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com<br>示例值：1200009811 |
| 模板id | plan\_id | string\[1,28\] | 是 | 协议模板id，设置路径见[开发步骤](https://pay.weixin.qq.com/doc/v2/merchant/4011986709.md)。<br>示例值：12535 |
| 签约协议号 | contract\_code | string\[1,128\] | 是 | 商户侧的签约协议号，由商户生成，只能是数字、大小写字母的描述且在同一个商户号下唯一。<br>示例值：100000 |
| 请求序列号 | request\_serial | int 64 | 是 | 商户请求签约时的序列号，要求唯一性。禁止使用0开头，序列号主要用于排序，不作为查询条件，纯数字，范围不能超过int64的范围（9223372036854775807）。<br>示例值：1000 |
| 用户账户展示名称 | contract\_display\_account | string\[1,128\] | 是 | 签约用户的名称，用于用户签约页面的“开通账号”处进行展示，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段<br>示例值：微信代扣 |
| 回调通知url | notify\_url | string\[1,256\] | 是 | 用于接收签约成功消息的回调通知地址，以http或https开头，通知url必须为外网可访问的url，不能携带参数。<br>请对notify\_url参数值进行encode处理,注意是对参数值进行encode，例如参数为notify\_url=“https://weixin.qq.com”，则需要encode的内容为https://weixin.qq.com。<br>携带参数类型需查看【[回调通知的接口文档](https://pay.weixin.qq.com/doc/v2/merchant/4011987586.md)】<br>示例值：https://weixin.qq.com |
| 签名 | sign | string\[1,32\] | 是 | 详见[签名生成算法](https://pay.weixin.qq.com/doc/v2/merchant/4011985891.md)<br>示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 时间戳 | timestamp | int 64 | 是 | 系统当前时间，10位<br>示例值：1414488825 |
| 商户侧用户标识 | outerid | string | 否 | 用户在商户侧的标识<br>示例值：1414488825 |
| 打开小程序的页面路径 | path | string\[1,64\] | 是 | 固定值：pages/index/index<br>示例值：pages/index/index |
| 接口调用成功的回调函数 | success | Function | 是 | - |
| 接口调用失败的回调函数 | fail | Function | 是 | - |
| 接口调用结束的回调函数 | complete | Function | 是 | 调用成功、失败都会执行 |

示例代码

```
wx.navigateToMiniProgram({
    appId:'wxbd687630cd02ce1d',
    path:'pages/index/index',
    extraData:{
        appid:'wx426a3015555a46be',
        contract_code:'122',
        contract_display_account:'张三',
        mch_id:'1223816102',
        notify_url:'https://www.qq.com/test/papay',
        plan_id:'106',
        request_serial:123,
        timestamp:1414488825,
        sign:'FF1A406564EE701064450CA2149E2514'
    },
success(res) {
    // 成功跳转到签约小程序
},
fail(res) {
    // 未成功跳转到签约小程序
}
})
```

用户签约完成之后，会跳转回商户小程序，可通过onShow(OBJECT)所携带的参数判断判断用户由签约小程序返回商户小程序，OBJECT返回参数请查看[小程序开发文档onShow参数说明](https://mp.weixin.qq.com/debug/wxadoc/dev/framework/app-service/app.html)

## referrerInfo.extraData字段说明

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 返回码 | return\_code | string\[1,16\] | 是 | 客户端小程序收到的签约结果<br>SUCCESS:签约成功<br>FAIL:签约失败<br>示例值：SUCCESS |
| 错误信息 | return\_msg | string\[1,128\] | 是 | 签约失败的错误信息<br>示例值： |
| 委托代扣协议id | contract\_id | string\[1,32\] | 是 | 签约成功后微信返回的委托代扣协议id<br>示例值：201710180325670965 |

注意：如果用户正常点击微信签约页的确定按钮返回商户小程序，那么会返回extraData ; 如果用户点击浏览器左上角的返回，则不返回extraData

示例代码

```
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;
                }
            }
        }
    }
})
```