开发指引
更新时间：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接口规则内容进行排查。
文档是否有帮助
