小程序调起签约api

更新时间：2024.12.30

应用场景

商户可以通过请求此接口唤起小程序委托代扣的签约页面，页面样例见案例与规范。

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

商户流程介绍

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

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

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

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

接口调用请求说明

接口	wx.navigateToMiniProgram(OBJECT)接口
说明	iOS 微信客户端 6.5.9 版本开始支持，Android 客户端即将在 6.5.10 版本开始支持

OBJECT参数说明：

字段含义

变量名

必填

示例值

类型

描述

微信签约小程序appid

appId

是

wxbd687630cd02ce1d

String

固定值
wxbd687630cd02ce1d

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

extraData

是

{"appid":"wx0317c726bd1c1111","mch_id":"1900000000","sub_mch_id":"1900000001","notify_url":"https://www.qq.com/a.php","contract_code":"2017121216136aa","contract_display_account":"张三","plan_id":"72803","request_serial":"1000","timestamp":"1513065696","sign":"63EE946A87EE1C8F6C12C1DB085C8B7E"}

object

签约的请求参数，详情见extraData字段详细说明

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

打开小程序的页面路径

path

是

pages/index/index

string

固定值：pages/index/index

接口调用成功的回调函数

success

是

Function

接口调用失败的回调函数

fail

是

Function

接口调用结束的回调函数

complete

是

Function

调用成功、失败都会执行

示例：

1wx.navigateToMiniProgram({
2    appId:'wxbd687630cd02ce1d',
3    path:'pages/index/index',
4    extraData:{
5        appid:'wx426a3015555a46be',
6        contract_code:'122',
7        contract_display_account:'张三',
8        mch_id:'1223816102',
9        sub_mch_id:'1223816104',
10        notify_url:'https://www.qq.com/test/papay',
11        plan_id:'106',
12        request_serial:'123',
13        timestamp:1414488825,
14        sign:'FF1A406564EE701064450CA2149E2514'
15    },
16success(res) {
17    // 成功跳转到签约小程序
18},
19fail(res) {
20    // 未成功跳转到签约小程序
21}
22})

用户签约完成之后，会跳转回商户小程序，可通过onShow(OBJECT)所携带的参数判断判断用户由签约小程序返回商户小程序，OBJECT返回参数请查看小程序开发文档onShow参数说明

referrerInfo.extraData字段说明

返回码	变量名	必填	示例值	类型	描述
返回码	return_code	是	SUCCESS	String	客户端小程序收到的签约结果 SUCCESS:签约成功 FAIL:签约失败
错误信息	return_msg	是		String	签约失败的错误信息
委托代扣协议id	contract_id	是	201710180325670965	String	签约成功后微信返回的委托代扣协议id

返回码

变量名

必填

示例值

类型

描述

返回码

return_code

是

SUCCESS

String

客户端小程序收到的签约结果

SUCCESS:签约成功

FAIL:签约失败

错误信息

return_msg

是

String

签约失败的错误信息

委托代扣协议id

contract_id

是

201710180325670965

String

签约成功后微信返回的委托代扣协议id

注意：

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

示例：

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

返回参数（异步返回）

签约成功后，微信会把相关签约结果异步发送给商户，返回的url为调用上述签约接口时填写的notify_url字段。商户在收到签约结果通知后，需进行接收处理并返回应答
对后台通知交互时，如果微信收到商户的应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率，但微信不保证通知最终能成功。
（通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒）
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

字段名	变量名	必填	示例值	类型	说明
返回状态码	return_code	是	SUCCESS	String(16)	SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
返回信息	return_msg	否	签名失败	String(128)	返回信息，如非空，为错误原因签名失败参数格式校验错误
以下字段在return_code为SUCCESS的时候返回
业务结果	result_code	是	SUCCESS	String(16)	SUCCESS/FAIL
以下字段在return_code 和result_code都为SUCCESS的时候有返回
商户号	mch_id	是	10000098	String(32)	微信支付分配的商户号
子商户号	sub_mch_id	是	1900000109	String(32)	微信支付分配的子商户号
签约协议号	contract_code	是	100001256	String(128)	签约协议号
模板id	plan_id	是	123	String	协议模板id
用户标识	openid	是	onqOjjmM1tad-3ROpncN-yUfa6ua	String(32)	Appid下，用户的唯一标识
用户子标识	sub_openid	否	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	String(32)	sub_appid下，用户的唯一标识
签名	sign	是	C380BEC2BFD727A4B6845133519F3AD6	String(32)	详见签名生成算法
变更类型	change_type	是	ADD	String(32)	有两个变更类型取值: ADD--签约 DELETE--解约
操作时间	operate_time	是	2015-07-01 10:00:00	String	操作时间
委托代扣协议id	contract_id	是	Wx15463511252015071056489715	String（32）	签约成功后，微信返回的委托代扣协议id
协议到期时间	contract_expired_time	是	2016-07-01 10:00:00	String	协议到期时间
请求序列号	request_serial	是	1695	String	商户请求签约时的序列号，商户侧须唯一,纯数字。长度不超过12位

示例：

1<xml>
2<return_code><![CDATA[SUCCESS]]></return_code>
3<result_code><![CDATA[SUCCESS]]></result_code>
4<sign><![CDATA[C380BEC2BFD727A4B6845133519F3AD6]]></sign>
5<mch_id>10010404</mch_id>
6<sub_mch_id>10010405</sub_mch_id>
7<contract_code>100001256</contract_code>
8<openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6ua]]></openid>
9<plan_id><![CDATA[123]]></plan_id>
10<change_type><![CDATA[ADD]]></change_type>
11<operate_time><![CDATA[2015-07-01 10:00:00]]></operate_time>
12<contract_id><![CDATA[Wx15463511252015071056489715]]></contract_id>
13</xml>

商户需返回参数

由于微信会多次通知商户服务器关于用户签约的结果和相关信息，为了避免给商户服务器造成过大的压力，请在得到微信签约结果通知之后，返回以下内容。（请求方式：post）

字段名	变量名	必填	示例值	类型	说明
返回状态码	return_code	是	SUCCESS	String(16)	SUCCESS/FAIL SUCCESS表示商户接收通知成功并校验成功
返回信息	return_msg	否	OK	String(32)	返回信息，如非空，为错误原因签名失败参数格式校验错误

商户返回示例：

1<xml>
2  <return_code><![CDATA[SUCCESS]]></return_code>
3  <return_msg><![CDATA[OK]]></return_msg>
4</xml>

微信支付签约，解约通知出口IP列表

如果商户侧配置了防火墙，需要对商户回调通知功能开通下面白名单网段：
101.226.233.128/25

文档是否有帮助

更多支持

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