开发指引

更新时间:2024.12.25

# 1. 接口规则

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

# 2. 开发准备

# 2.1. 搭建和配置开发环境

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

# 3. 快速接入

# 3.1. 业务流程图

#

重点步骤说明:

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

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

# 3.2. API接入(含示例代码)

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

注意

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

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

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

示例代码
1public void BuildRelations() throws Exception{
2 //请求URL
3 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/marketing/partnerships/build");
4 // 请求body参数
5 String reqdata = "{"
6 + "\"authorized_data\": {"
7 + "\"business_type\":\"FAVOR_STOCK\","
8 + "\"stock_id\":\"2433405\""
9 + "},"
10 + "\"partner\": {"
11 + "\"appid\":\"wx4e1916a585d1f4e9\","
12 + "\"type\":\"APPID\""
13 + "}"
14 + "}";
15 StringEntity entity = new StringEntity(reqdata,"utf-8");
16 entity.setContentType("application/json");
17 httpPost.setEntity(entity);
18 httpPost.setHeader("Accept", "application/json");
19 httpPost.setHeader("Idempotency-Key","12345");
20 //完成签名并执行请求
21 CloseableHttpResponse response = httpClient.execute(httpPost);
22
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}
1try {
2 $resp = $client->request(
3 'POST',
4 'https://api.mch.weixin.qq.com/v3/marketing/partnerships/build', //请求URL
5 [
6 // JSON请求体
7 'json' => [
8 "authorized_data" => [
9 "business_type" => "FAVOR_STOCK",
10 "stock_id" => "2433405",
11 ],
12 "partner" => [
13 "appid" => "wx4e1916a585d1f4e9",
14 "type" => "APPID",
15 ]
16 ],
17 'headers' => [
18 'Accept' => 'application/json',
19 'Idempotency-Key' => '12345'
20 ]
21 ]
22 );
23 $statusCode = $resp->getStatusCode();
24 if ($statusCode == 200) { //处理成功
25 echo "success,return body = " . $resp->getBody()->getContents()."\n";
26 } else if ($statusCode == 204) { //处理成功,无返回Body
27 echo "success";
28 }
29} catch (RequestException $e) {
30 // 进行错误处理
31 echo $e->getMessage()."\n";
32 if ($e->hasResponse()) {
33 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
34 }
35 return;
36}

重要入参说明:

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

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

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

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

示例代码
1public void QueryRelations() throws Exception{
2 //请求URL
3 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");
4 httpGet.setHeader("Accept", "application/json");
5
6 //完成签名并执行请求
7 CloseableHttpResponse response = httpClient.execute(httpGet);
8
9 try {
10 int statusCode = response.getStatusLine().getStatusCode();
11 if (statusCode == 200) { //处理成功
12 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
13 } else if (statusCode == 204) { //处理成功,无返回Body
14 System.out.println("success");
15 } else {
16 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
17 throw new IOException("request failed");
18 }
19 } finally {
20 response.close();
21 }
22}
1try {
2 $resp = $client->request(
3 'GET',
4 '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
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}

重要入参说明:

  • business_type: 授权业务类别,枚举值:
    • FAVOR_STOCK:代金券批次
    • BUSIFAVOR_STOCK:商家券批次

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

# 4. 常见问题

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

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

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

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

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

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

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

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

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

A:请求头中的API证书序列号错误,请排查确认。证书序列号查看路径:【服务商平台 (opens new window)->API安全->API证书->查看证书】。

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

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

反馈
咨询
目录

微信支付文档中心已升级,你当前所查看的是旧文档中心的内容,旧文档中心将于 2025年 3 月 31日 下线,请移步 [新文档中心] 查看相应的内容