开发指引

更新时间：2024.11.15

1. 接口规则

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

2. 开发准备

2.1. 搭建和配置开发环境

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

3. 快速接入

3.1. 业务流程图

重点步骤说明：

步骤4 商户调用《建立合作关系》接口，将指定优惠券批次（支付券或商家券）授权给指定AppID。

步骤7 用户在商家小程序直播间，可领取对应优惠券；（优惠券领取后，自动插入用户微信卡包）。

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

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

注意

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

3.2.1. 【服务端】建立合作关系

步骤说明：该接口主要为商户提供营销资源的授权能力，可授权给其他商户或小程序，方便商户间的互利合作。

Java

1示例代码
2public void BuildRelations() throws Exception{
3    //请求URL
4    HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/marketing/partnerships/build");
5    // 请求body参数
6    String reqdata = "{"
7            + "\"authorized_data\": {"
8            + "\"business_type\":\"FAVOR_STOCK\","
9            + "\"stock_id\":\"2433405\""
10            + "},"
11            + "\"partner\": {"
12            + "\"appid\":\"wx4e1916a585d1f4e9\","
13            + "\"type\":\"APPID\""
14            + "}"
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    httpPost.setHeader("Idempotency-Key","12345");
21    //完成签名并执行请求
22    CloseableHttpResponse response = httpClient.execute(httpPost);
23    try {
24        int statusCode = response.getStatusLine().getStatusCode();
25        if (statusCode == 200) { //处理成功
26            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
27        } else if (statusCode == 204) { //处理成功，无返回Body
28            System.out.println("success");
29        } else {
30            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
31            throw new IOException("request failed");
32        }
33    } finally {
34        response.close();
35    }
36}

PHP

1示例代码
2  try {
3    $resp = $client->request(
4        'POST',
5        'https://api.mch.weixin.qq.com/v3/marketing/partnerships/build', //请求URL
6        [
7            // JSON请求体
8            'json' => [
9                "authorized_data" => [
10                    "business_type" => "FAVOR_STOCK", 
11                    "stock_id" => "2433405", 
12                ],
13                "partner" => [
14                    "appid" => "wx4e1916a585d1f4e9", 
15                    "type" => "APPID", 
16                ]
17            ],
18            'headers' => [ 
19                'Accept' => 'application/json',
20                'Idempotency-Key' => '12345'
21            ]
22        ]
23    );
24    $statusCode = $resp->getStatusCode();
25    if ($statusCode == 200) { //处理成功
26        echo "success,return body = " . $resp->getBody()->getContents()."\n";
27    } else if ($statusCode == 204) { //处理成功，无返回Body
28        echo "success";
29    }
30} catch (RequestException $e) {
31    // 进行错误处理
32    echo $e->getMessage()."\n";
33    if ($e->hasResponse()) {
34        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
35    }
36    return;
37}

重要入参说明：

type：合作方类别，枚举值：
- AppID：合作方为AppID
- MERCHANT：合作方为商户
business_type：授权业务类别，枚举值：
- FAVOR_STOCK：代金券批次
- BUSIFAVOR_STOCK：商家券批次

更多参数、响应详情及错误码请参见建立合作关系接口文档。

3.2.2. 【服务端】查询合作关系列表

步骤说明：该接口主要为商户提供合作关系列表的查询能力。

Java

1示例代码
2public void QueryRelations() throws Exception{
3    //请求URL
4    HttpGet httpGet = new HttpGet("https://api.mch.weixin.qq.com/v3/marketing/partnerships?authorized_data=%7b%22business_type%22%3a%22BUSIFAVOR_STOCK%22%7d&partner=%7b%22type%22%3a%22APPID%22%7d&offset=0&limit=5");
5    httpGet.setHeader("Accept", "application/json");
6    //完成签名并执行请求
7    CloseableHttpResponse response = httpClient.execute(httpGet);
8    try {
9        int statusCode = response.getStatusLine().getStatusCode();
10        if (statusCode == 200) { //处理成功
11            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
12        } else if (statusCode == 204) { //处理成功，无返回Body
13            System.out.println("success");
14        } else {
15            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
16            throw new IOException("request failed");
17        }
18    } finally {
19        response.close();
20    }
21}

PHP

1示例代码
2try {
3    $resp = $client->request(
4        'GET',
5        'https://api.mch.weixin.qq.com/v3/marketing/partnerships?authorized_data=%7b%22business_type%22%3a%22BUSIFAVOR_STOCK%22%7d&partner=%7b%22type%22%3a%22APPID%22%7d&offset=0&limit=5', //请求URL
6        [
7            'headers' => [ 'Accept' => 'application/json']
8        ]
9    );
10    $statusCode = $resp->getStatusCode();
11    if ($statusCode == 200) { //处理成功
12        echo "success,return body = " . $resp->getBody()->getContents()."\n";
13    } else if ($statusCode == 204) { //处理成功，无返回Body
14        echo "success";
15    }
16} catch (RequestException $e) {
17    // 进行错误处理
18    echo $e->getMessage()."\n";
19    if ($e->hasResponse()) {
20        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
21    }
22    return;
23}

重要入参说明：

business_type：授权业务类别，枚举值：
- FAVOR_STOCK：代金券批次
- BUSIFAVOR_STOCK：商家券批次

更多参数、响应详情及错误码请参见查询合作关系列表接口文档。

4. 常见问题

Q：调用建立合作关系接口返回“AppID与mchid不匹配”

A：请按照以下几点检查：

AppID或mch_id填写错误，请确认AppID和mch_id是否正确。
AppID与mch_id未绑定，请绑定后再调用接口，绑定步骤请参考《绑定指引》文档。

Q：调用建立合作关系接口返回“商户号不存在”

A：商户号不存在，请确认请求头中的商户号是否正确或者是否有空格。

Q：查询合作关系列表API返回“签名错误或签名信息不完整”

A：请按照以下几点检查：

签名与生成Authorization用的同一个时间戳跟随机串。
构造签名串时，里面的URL不需要ToLowCase()，不用UrlEncode()，商户请求的URL后缀是什么，签名用的URL后缀就是什么。
查询订单使用的是GET，构建签名串时，里面的请求报文为空且需要换行符。
检查证书和商户号是否正确，如为服务商模式，则需使用服务商的相关证书。签名相关问题请参考《接口规则》文档。

Q：调用建立合作关系接口返回“商户证书序列号有误。请使用签名私钥匹配的证书序列号”

A：请求头中的API证书序列号错误，请排查确认。证书序列号查看路径：【商户平台->API安全->API证书->查看证书】。

Q：调用建立合作关系接口返回“HTTP头缺少Accept或User-Agent”

A：HTTP头缺少Accept或User-Agent，请根据V3接口规则内容进行排查。

文档是否有帮助

更多支持

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