开发指引
更新时间: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 //请求URL3 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);2223 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) { //处理成功,无返回Body28 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', //请求URL5 [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) { //处理成功,无返回Body27 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 //请求URL3 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");56 //完成签名并执行请求7 CloseableHttpResponse response = httpClient.execute(httpGet);89 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) { //处理成功,无返回Body14 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', //请求URL5 [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) { //处理成功,无返回Body13 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接口规则内容进行排查。
文档是否有帮助