APP签约

更新时间：2025.03.21

用户在商户的APP中发起签约，跳转到微信客户端签约小程序完成签约，签约完成后重新打开商户APP。移动应用（APP）接入开放平台SDK后，用户即可以在 APP 中跳转至微信某一小程序的指定页面，完成服务后再跳回至商户APP。

注意：

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

步骤1：预签约API

1. 接口说明

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

请求URL：https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/app-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]	是	Body HTTPS开头的回调通知URL ,不需要对值进行URL编码示例值：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	  "sp_appid": "wxcbda96de0b165486",
7	  "sub_appid": "wxcbda96de0b165484",
8	  "sub_mchid": "10000097",
9	  "success_notify_url": "https://yoursite.com",
10	  "user_client_ip": "119.145.83.6",
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：签约接口

时序图

简介

App跳转微信侧小程序需要引用新的openSDK

Android openSDK下载地址（版本>=5.3.1）：Android资源下载

Android 接入文档链接：openSDK说明文档/

接口名称：WXOpenBusinessViewReq

iOS openSDK下载地址（版本>=1.8.4）：iOS资源下载

iOS 接入文档链接：openSDK说明文档

接口名称：WXOpenBusinessViewReq

HarmonyOS NextopenSDK下载地址（版本>=1.0.5）：HarmonyOS Next资源下载

HarmonyOS Next接入文档链接：openSDK说明文档

接口名称：OpenBusinessViewReq

接口兼容：

● iOS兼容性表现：若微信版本 >= 7.0.3，开发者可以通过此openSDK接口跳转到微信支付分小程序；若微信版本 < 7.0.3，开发者通过此openSDK接口可以跳转到微信，但不能跳转到微信支付分小程序，此时微信会提示用户可能由于应用的请求非法或者微信版本过低。
● Android兼容性表现：若微信版本>=7.0.3，开发者可以通过此openSDK接口跳转到微信支付分小程序；若微信版本 < 7.0.3，开发者通过此openSDK接口不能跳转到微信，此时开发者应提示用户更新微信版本。
● HarmonyOS Next兼容性表现：若微信版本>=1.0.3，开发者可以通过此openSDK接口跳转到微信支付分小程序；若微信版本 < 1.0.3，开发者通过此openSDK接口不能跳转到微信，此时开发者应提示用户更新微信版本。

请求参数

参数名	变量	类型[长度限制]	必填	描述
跳转类型	businessType	string[1, 32]	是	固定值：wxpayOverseaEntrustAuthorization 示例值：wxpayOverseaEntrustAuthorization
委托代扣签约会话ID	sessionId	string[1, 128]	是	预签约API中的返回值 session_id，由 APP 预签约接口获得示例值：201710180325670965

请求示例

场景一：IOS

1WXOpenBusinessViewReq *req = [WXOpenBusinessViewReq object];
2req.businessType = @"wxpayOverseaEntrustAuthorization"; // 固定值
3req.query = @"sessionId=20211115171992080208"; // 20211115171992080208为预签约会话ID
4req.extInfo = @"{\"miniProgramType\":0}"; // 固定值
5[WXApi sendReq:req];

场景二：Android

1// 发起签约
2int wxSdkVersion = api.getWXAppSupportAPI();
3if (wxSdkVersion >= Build.OPEN_BUSINESS_VIEW_SDK_INT) {
4WXOpenBusinessView.Req req = new WXOpenBusinessView.Req();
5req.businessType = "wxpayOverseaEntrustAuthorization"; // 固定值
6String SesssionId = "20211115171992080208"; // 预签约会话ID，通过下述预签约API获取
7req.query = "sessionId=" + SesssionId; // 拼接参数
8req.extInfo = "{\"miniProgramType\": 0}"; // 固定值
9Boolean ret = api.sendReq(req);
10} else {
11// 微信版本太低，在这里提示用户升级后再完成签约
12}
13
14/********在WXEntryActivity的onResp里面接收签约结束回调，示例代码*******/
15@Override
16public void onResp(BaseResp r) {
17if (r.getType() == ConstantsAPI.COMMAND_OPEN_BUSINESS_VIEW) {
18WXOpenBusinessView.Resp launchMiniProgramResp = (WXOpenBusinessView.Resp) r;
19String text = String.format("nextMsg=%snerrStr=%snbusinessType=%s",
20resp.extMsg, resp.errStr, resp.businessType);
21Toast.makeText(this, text, Toast.LENGTH_lONG).show();
22// 对应时序图步骤3.4 - 3.6，调用查询签约API获取协议最新状态，然后更新商户侧签约状态
23}
24}

场景三：HarmonyOS Next

1import * as wxopensdk from '@tencent/wechat_open_sdk'; // Import wxopensdk
2
3
4// Handle WeChat callback response. Registration method refers to: https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Access_Guide/ohos.html `4. Using SDK in code`
5class CustomWXEventHandler implements wxopensdk.WXApiEventHandler {
6  onResp(resp: wxopensdk.BaseResp): void {
7    if (resp instanceof wxopensdk.OpenBusinessViewResp) {
8      if ("wxpayOverseaEntrustAuthorization" === resp.businessType) {
9        // Process the entrustment authorization result
10      }
11    }
12  }
13}
14
15export const WXApi = wxopensdk.WXAPIFactory.createWXAPI(APP_ID); // APP_ID is the mobile app's appid, it's recommended to share the same WXApi instance globally
16const eventHandler = new CustomWXEventHandler();
17
18// Send entrustment authorization request
19async sendWxPayOverseaEntrustAuthorization() {
20  // 1. Pre-registering event handlers
21  WXApi.handleWant({}, eventHandler);
22
23  // 2. Setting parameters
24  let req = new wxopensdk.OpenBusinessViewReq;
25  req.businessType = "wxpayOverseaEntrustAuthorization"; // Fixed value
26  let sesssionId = "20211115171992080208"; // Pre-entrustment session ID obtained via the pre-entrustment API
27  req.query = "sessionId=" + sesssionId; // Parameter concatenation
28  req.extInfo = "{miniProgramType:0}"; // Fixed value
29
30  // 3. Request
31  let finished = await WXApi.sendReq(getContext(this) as common.UIAbilityContext, req); // Send request to WeChat client, where "this" refers to the current component
32}