开发指引

更新时间：2024.11.29

1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。

2. 开发准备

2.1. 搭建和配置开发环境

开发者应当依据自身的编程语言来构建并配置相应的开发环境。

2.2. 业务开发配置

1. 登录【微信支付服务商平台】后，通过路径【产品中心—>我的产品—>支付即服务—>产品设置】，即可开通支付即服务，开通后完成产品设置。

2. 【产品设置】页面如下图所示，具体内容包括上传商家logo、选择服务人员名称及选择名片功能模块。

3. 快速接入

3.1. 业务流程图

重点步骤说明：

步骤6：使用企业微信的商户，通过《服务人员注册API》接口传入服务人员信息进行注册，微信支付返回服务人员ID给到商户，商户需将服务人员注册信息和对应的服务人员ID进行妥善保存。

步骤11：商户在下单时生成商户订单号，接着调用《服务人员分配API》传入“商户订单号+服务人员ID”，随后按照原有流程和支付接口完成支付即可。

3.2. API接入（含示例代码）

文档展示了如何使用微信支付服务端 SDK 快速接入商家券产品，完成与微信支付对接的部分。

注意

文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1. 【服务端】服务人员注册

步骤说明：商户开发者使用「服务人员注册接口」为商户注册服务人员。

注意

调用接口前商家需完成支付即服务产品的开通和设置。若普通服务商为特约商户调用接口，需在特约商户开通并完成产品设置后，与特约商户建立产品授权关系。

示例代码
JAVA

1public void RegSmartGuide() throws Exception{
2    //请求URL
3    HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/smartguide/guides");
4    // 请求body参数
5    String reqdata = "{"
6            + "\"sub_mchid\":\"1234567890\","
7            + "\"store_id\":1234,"
8            + "\"corpid\":\"1234567890\","
9            + "\"name\":\"pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==\","
10            + "\"mobile\":\"pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==\","
11            + "\"qr_code\":\"https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx\","
12            + "\"avatar\":\"http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0\","
13            + "\"group_qrcode\":\"http://p.qpic.cn/wwhead/nMl9ssowtibVGyrmvBiaibzDtp/0\","
14            + "\"userid\":\"robert\""
15            + "}";
16    StringEntity entity = new StringEntity(reqdata,"utf-8");
17    entity.setContentType("application/json");
18    httpPost.setEntity(entity);
19    httpPost.setHeader("Accept", "application/json");
20    //完成签名并执行请求
21    CloseableHttpResponse response = httpClient.execute(httpPost);
22    try {
23        int statusCode = response.getStatusLine().getStatusCode();
24        if (statusCode == 200) { //处理成功
25            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
26        } else if (statusCode == 204) { //处理成功，无返回Body
27            System.out.println("success");
28        } else {
29            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
30            throw new IOException("request failed");
31        }
32    } finally {
33        response.close();
34    }
35}

PHP

1try {
2    $resp = $client->request(
3        'POST',
4        'https://api.mch.weixin.qq.com/v3/smartguide/guides', //请求URL
5        [
6            // JSON请求体
7            'json' => [
8                "store_id" => 1234, 
9                "sub_mchid" => "1234567890", 
10                "corpid" => "1234567890", 
11                "name" => "pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==", 
12                "mobile" => "pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==", 
13                "qr_code" => "https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx", 
14                "avatar" => "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0", 
15                "group_qrcode" => "http://p.qpic.cn/wwhead/nMl9ssowtibVGyrmvBiaibzDtp/0", 
16                "userid" => "robert",
17            ],
18            'headers' => [ 'Accept' => 'application/json' ]
19        ]
20    );
21    $statusCode = $resp->getStatusCode();
22    if ($statusCode == 200) { //处理成功
23        echo "success,return body = " . $resp->getBody()->getContents()."\n";
24    } else if ($statusCode == 204) { //处理成功，无返回Body
25        echo "success";
26    }
27} catch (RequestException $e) {
28    // 进行错误处理
29    echo $e->getMessage()."\n";
30    if ($e->hasResponse()) {
31        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
32    }
33    return;
34}

重要入参说明：

store_id：门店在微信支付商户平台的唯一标识（查找路径：登录商户平台—>营销中心—>门店管理，若无门店则需先创建门店）。
name：员工在商户企业微信通讯录上的姓名，该字段需要使用微信支付公钥加密（推荐），请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引，也可以使用微信支付平台证书公钥加密，参考获取平台证书序列号、平台证书加密敏感信息指引。特殊规则：加密前字段长度限制为64个字节。

更多参数、响应详情及错误码请参见服务人员注册API接口文档。

3.2.2. 【服务端】服务人员分配

步骤说明：服务人员分配接口用于商户开发者在顾客下单后为顾客分配服务人员使用。

注意

调用服务人员分配接口需在完成支付之前，若分配服务人员晚于支付完成，则将无法在支付凭证上出现服务人员名片入口。

示例代码

JAVA

1public void AssignGuide() throws Exception{
2    //请求URL
3    HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/smartguide/guides/LLA3WJ6DSZUfiaZDS79FH5Wm5m4X69TBic/assign");
4    // 请求body参数
5    String reqdata = "{"
6            + "\"out_trade_no\":\"20150806125346\""
7            + "\"sub_mchid\":\"1234567890\""
8            + "}";
9    StringEntity entity = new StringEntity(reqdata,"utf-8");
10    entity.setContentType("application/json");
11    httpPost.setEntity(entity);
12    httpPost.setHeader("Accept", "application/json");
13    //完成签名并执行请求
14    CloseableHttpResponse response = httpClient.execute(httpPost);
15    try {
16        int statusCode = response.getStatusLine().getStatusCode();
17        if (statusCode == 200) { //处理成功
18            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
19        } else if (statusCode == 204) { //处理成功，无返回Body
20            System.out.println("success");
21        } else {
22            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
23            throw new IOException("request failed");
24        }
25    } finally {
26        response.close();
27    }
28}

PHP

1try {
2    $resp = $client->request(
3        'POST',
4        'https://api.mch.weixin.qq.com/v3/smartguide/guides/LLA3WJ6DSZUfiaZDS79FH5Wm5m4X69TBic/assign', //请求URL
5        [
6            // JSON请求体
7            'json' => [
8                "out_trade_no" => "20150806125346",
9                "sub_mchid" => "1234567890",
10            ],
11            'headers' => [ 'Accept' => 'application/json' ]
12        ]
13    );
14    $statusCode = $resp->getStatusCode();
15    if ($statusCode == 200) { //处理成功
16        echo "success,return body = " . $resp->getBody()->getContents()."\n";
17    } else if ($statusCode == 204) { //处理成功，无返回Body
18        echo "success";
19    }
20} catch (RequestException $e) {
21    // 进行错误处理
22    echo $e->getMessage()."\n";
23    if ($e->hasResponse()) {
24        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
25    }
26    return;
27}

重要入参说明：

out_trade_no：商户系统内部订单号，要求32个字符内，仅支持使用字母、数字、中划线-、下划线_、竖线|、星号*这些英文半角字符的组合，请勿使用汉字或全角等特殊字符，且在同一个商户号下唯一。

更多参数、响应详情及错误码请参见服务人员分配API接口文档。

3.2.3. 【服务端】服务人员查询

步骤说明：服务人员查询接口用于商户开发者查询已注册的服务人员ID等信息。

注意

个人微信商家：

传入门店ID，查询该门店下的所有已注册服务人员的信息（每次查询不可超过10条）。
传入服务人员的工号（服务人员注册时填写）或手机号，查询单个服务人员的信息。

企业微信商家：

传入门店ID，查询该门店下的所有已注册服务人员的信息（每次查询不可超过10条）。
传入服务人员的企业微信员工ID或手机号，查询单个服务人员的信息。

服务人员注册API和查询API请求URL相同，区别主要是在body和query，请注意区分。

示例代码

JAVA

1public void QueryGuide() throws Exception{
2    //请求URL
3    HttpGet httpGet = new HttpGet("https://api.mch.weixin.qq.com/v3/smartguide/guides?store_id=1234&sub_mchid=1234567890");
4    httpGet.setHeader("Accept", "application/json");
5    //完成签名并执行请求
6    CloseableHttpResponse response = httpClient.execute(httpGet);
7    try {
8        int statusCode = response.getStatusLine().getStatusCode();
9        if (statusCode == 200) { //处理成功
10            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
11        } else if (statusCode == 204) { //处理成功，无返回Body
12            System.out.println("success");
13        } else {
14            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
15            throw new IOException("request failed");
16        }
17    } finally {
18        response.close();
19    }
20}

PHP

1try {
2    $resp = $client->request(
3        'GET',
4        'https://api.mch.weixin.qq.com/v3/smartguide/guides?store_id=1234&=sub_mch=1234567890', //请求URL
5        [
6            'headers' => [ 'Accept' => 'application/json']
7        ]
8    );
9    $statusCode = $resp->getStatusCode();
10    if ($statusCode == 200) { //处理成功
11        echo "success,return body = " . $resp->getBody()->getContents()."\n";
12    } else if ($statusCode == 204) { //处理成功，无返回Body
13        echo "success";
14    }
15} catch (RequestException $e) {
16    // 进行错误处理
17    echo $e->getMessage()."\n";
18    if ($e->hasResponse()) {
19        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20    }
21    return;
22}

重要入参说明：

userid：员工在商户企业微信通讯录使用的唯一标识，企业微信商家可传入该字段查询单个服务人员信息；不传则查询整个门店下的服务人员信息。

更多参数、响应详情及错误码请参见服务人员查询API接口文档。

3.2.4. 【服务端】服务人员信息更新

步骤说明：服务人员信息更新接口用于商户开发者为商户更新门店服务人员的姓名、头像等信息。

注意

个人微信商家、企业微信商家均支持服务人员信息更新。

示例代码

JAVA

1public void UpdateGuide() throws Exception{
2    //请求URL
3    HttpPatch httpPatch = new HttpPatch("https://api.mch.weixin.qq.com/v3/smartguide/guides/LLA3WJ6DSZUfiaZDS79FH5Wm5m4X69TBic");
4    // 请求body参数
5    String reqdata = "{"
6            + 
7"\"sub_mchid\":\"1234567890\","
8            + 
9"\"name\":\"pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==\","
10            + "\"mobile\":\"pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==\","
11            + "\"qr_code\":\"https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx\","
12            + "\"avatar\":\"http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0\","
13            + "\"group_qrcode\":\"http://p.qpic.cn/wwhead/nMl9ssowtibVGyrmvBiaibzDtp/0\""
14            + "}";
15    StringEntity entity = new StringEntity(reqdata,"utf-8");
16    entity.setContentType("application/json");
17    httpPatch.setEntity(entity);
18    httpPatch.setHeader("Accept", "application/json");
19    //完成签名并执行请求
20    CloseableHttpResponse response = httpClient.execute(httpPatch);
21    try {
22        int statusCode = response.getStatusLine().getStatusCode();
23        if (statusCode == 200) { //处理成功
24            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
25        } else if (statusCode == 204) { //处理成功，无返回Body
26            System.out.println("success");
27        } else {
28            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
29            throw new IOException("request failed");
30        }
31    } finally {
32        response.close();
33    }
34}

PHP

1try {
2    $resp = $client->request(
3        'PATCH',
4        'https://api.mch.weixin.qq.com/v3/smartguide/guides/LLA3WJ6DSZUfiaZDS79FH5Wm5m4X69TBic', //请求URL
5        [
6            // JSON请求体
7            'json' => [
8                "name" => "pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==", 
9                "mobile" => "pVd1HJ6v/69bDnuC4EL5Kz4jBHLiCa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==", 
10                "qr_code" => "https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx", 
11                "avatar" => "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0", 
12                "group_qrcode" => "http://p.qpic.cn/wwhead/nMl9ssowtibVGyrmvBiaibzDtp/0",
13                "sub_mchid" => "1234567890",
14            ],
15            'headers' => [ 'Accept' => 'application/json' ]
16        ]
17    );
18    $statusCode = $resp->getStatusCode();
19    if ($statusCode == 200) { //处理成功
20        echo "success,return body = " . $resp->getBody()->getContents()."\n";
21    } else if ($statusCode == 204) { //处理成功，无返回Body
22        echo "success";
23    }
24} catch (RequestException $e) {
25    // 进行错误处理
26    echo $e->getMessage()."\n";
27    if ($e->hasResponse()) {
28        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
29    }
30    return;
31}

重要入参说明：

guide_id：务人员在支付即服务系统中的唯一标识。

更多参数、响应详情及错误码请参见服务人员信息更新API接口文档。

4. 常见问题

Q：使用服务人员注册API进行注册时，sub_mchid（子商户ID）应该传什么？

A：如果是普通特约商户自己调接口，不传即可；如果是普通服务商帮特约商户调接口，传特约商户的商户号。

Q：企业微信的corpid如何获取？

A：获取corpid可进入企业微信的管理后台，查找路径：【我的企业->企业信息→查看“企业ID”】（需要有管理员权限）。

Q：注册服务人员时必须传入门店ID吗？在哪里找这个门店ID

A：是的，注册时必须传入门店ID。该门店ID是微信支付门店系统的编码，查找路径：【登录商户平台->营销中心→门店管理】，门店管理页面下的门店编号即为需要填写的门店ID（该门店信息与企业微信的门店系统无关）。

若未创建门店，则需创建门店并通过腾讯地图审核后，方可使用门店ID进行注册。

Q：调用服务人员分配接口是在支付前还是支付后？

A：支付前。建议当商家生成当前交易的“商户订单号”时，通过“服务人员分配API”将“服务人员ID+商户订单号”传给微信支付，并按照原有流程引导用户完成支付即可。若分配服务人员晚于支付完成，则将无法在支付凭证上出现服务人员名片入口。

Q：服务人员分配应该采取什么样的分配机制？

A：使用服务人员分配API进行分配时，服务人员的分配机制由商家内部闭环，可以灵活掌控。在支付前调用分配接口时，商家可自行决定分配哪名服务人员，商家可选择随机分配、按时间段分配，或为某笔订单指定特定服务人员的分配方式（例如在线下门店支付时，可分配当前为该顾客提供服务的服务人员）。使用免开发版本时，商户号下的所有订单将随机分配给不同服务人员，商家可通过小程序调整服务人员分配的时间段，但是不能针对不同订单分配特定的服务人员。

文档是否有帮助

更多支持

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