开发指引
更新时间：2023.08.22# 1. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
# 2. 开发准备
# 2.1. 搭建和配置开发环境
为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传 等基础功能（更多语言版本的开发库将在近期陆续提供）。
测试步骤：
1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：
- wechatpay-java (opens new window)（推荐）、wechatpay-apache-httpclient (opens new window)，适用于Java开发者。
- 注：当前开发指引接口JAVA示例代码采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推荐）、wechatpay-guzzle-middleware (opens new window)，适用于PHP开发者。
- 注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，适用于Go开发者。
更多资源可前往微信支付开发者社区 (opens new window)搜索查看。
2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法。
3、基于接口的示例代码，替换请求参数后可发起测试。
说明：
- 上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性。通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。
- 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：
- 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。
# 3. 快速接入
# 3.1. 业务流程图
重点步骤说明：
步骤4 商户调用建立合作关系接口，将指定优惠券批次（支付券或商家券）授权给指定AppID。
步骤7 用户在商家小程序直播间，可领取对应优惠券；（优惠券领取后，自动插入用户微信卡包）。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入商家券产品，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】建立合作关系
步骤说明： 该接口主要为商户提供营销资源的授权能力，可授权给其他商户或小程序，方便商户间的互利合作。
重要入参说明：
- type： 合作方类别，枚举值：
- AppID：合作方为AppID
- MERCHANT：合作方为商户
- business_type： 授权业务类别，枚举值：
- FAVOR_STOCK：代金券批次
- BUSIFAVOR_STOCK：商家券批次
更多参数、响应详情及错误码请参见建立合作关系接口文档。
# 3.2.2. 【服务端】查询合作关系列表
步骤说明： 该接口主要为商户提供合作关系列表的查询能力。
重要入参说明：
- 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接口规则内容进行排查。
