开发指引
更新时间：2023.09.09# 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. 业务流程图
重点步骤说明：
步骤3： 用户发起投诉后，微信支付通过投诉通知回调通知商户投诉单需处理。
步骤6： 商户接收投诉后，可通过回复用户API接口向微信支付提交投诉处理回复。
步骤9： 与用户协商一致后，商户通过反馈处理完成API反馈投诉单处理完成。
步骤15： 商户在没有接收到微信投诉通知的情况下可主动调用查询投诉单详情查询投诉单处理结果。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】查询投诉单列表
步骤说明：商户可通过调用此接口，查询指定时间段的所有用户投诉信息，以分页输出查询结果。
重要入参说明：
- begin_date： 开始日期，投诉发生的开始日期，格式为yyyy-MM-dd。注意，查询日期跨度不超过30天。
- end_date： 结束日期，投诉发生的结束日期，格式为yyyy-MM-dd。注意，查询日期跨度不超过30天。
更多参数、响应详情及错误码请参见查询投诉单列表接口文档。
# 3.2.2.【服务端】查询投诉单详情
步骤说明：商户可通过调用此接口，查询指定投诉单的用户投诉详情，包含投诉内容、投诉关联订单、投诉人联系方式等信息，方便商户处理投诉。
重要入参说明：
- complaint_id： 投诉单对应的投诉单号，在投诉通知回调中会返回这个参数。
更多参数、响应详情及错误码请参见查询投诉单详情接口文档。
# 3.2.3. 【服务端】查询投诉协商历史
步骤说明： 商户可通过调用此接口，查询指定投诉的用户商户协商历史，以分页输出查询结果，方便商户根据处理历史来制定后续处理方案。
重要入参说明：
- complaint_id： 投诉单对应的投诉单号，在投诉通知回调中会返回这个参数。
更多参数、响应详情及错误码请参见查询投诉协商历史接口文档。
# 3.2.4. 【服务端】投诉通知回调
步骤说明： 商户创建投诉通知回调URL 后，当有新的投诉事件发生、投诉状态发生变化时，商户会收到通知回调。商户需要接收处理，并按文档规范返回应答。
注意
- 投诉通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 投诉通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204。
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
更多参数、响应详情及错误码请参见投诉通知回调接口文档。
# 3.2.5. 【服务端】创建投诉通知回调地址
步骤说明： 商户通过调用此接口创建投诉通知回调URL，当用户产生新投诉且投诉状态已变更时，微信支付会通过回调URL通知商户。
重要入参说明：
- URL: 通知地址，通知地址，仅支持HTTPS。
更多参数、响应详情及错误码请参见创建投诉通知回调地址接口文档。
# 3.2.6.【服务端】查询投诉通知回调地址
步骤说明： 商户通过调用此接口查询投诉通知的回调URL。
更多参数、响应详情及错误码请参见查询投诉通知回调地址接口文档。
# 3.2.7. 【服务端】更新投诉通知回调地址
步骤说明： 商户通过调用此接口创建投诉通知回调URL，当用户产生新投诉且投诉状态已变更时，微信支付会通过回 调URL通知商户。
重要入参说明：
- URL: 通知地址，通知地址，仅支持HTTPS。
更多参数、响应详情及错误码请参见更新投诉通知回调地址接口文档。
# 3.2.8. 【服务端】删除投诉通知回调地址
步骤说明： 商户通过调用此接口查询投诉通知的回调URL。
更多参数、响应详情及错误码请参见删除投诉通知回调地址接口文档。
# 3.2.9. 【服务端】提交回复
步骤说明：商户可调用此接口回复用户。其中上传图片凭证需首先调用商户上传反馈图片接口，得到图片ID，再将ID填入请求。
重要入参说明：
- complaint_id： 投诉单对应的投诉单号。
- complainted_mchid： 被诉商户号，投诉单对应的被诉商户号。
- response_content： 回复内容，具体的投诉处理方案，限制200个字符以内。
更多参数、响应详情及错误码请参见提交回复接口文档。
# 3.2.10. 【服务端】反馈处理完成
步骤说明： 商户可通过调用此接口，反馈投诉单已处理完成。
重要入参说明：
- complaint_id： 投诉单对应的投诉单号，在投诉通知回调中会返回这个参数。
- complainted_mchid： 被诉商户号，投诉单对应的被诉商户号。
更多参数、响应详情及错误码请参见反馈处理完成接口文档。
# 3.2.11. 【服务端】商户上传反馈图片
步骤说明： 商户上传反馈图片的接口。 将媒体图片进行二进制转换，得到的媒体图片二进制内容，在请求body中上传此二进制内容。 媒体图片只支持jpg、png、bmp格式，文件大小不能超过2M。
重要入参说明：
- file： 图片文件，将媒体图片进行二进制转换，得到的媒体图片二进制内容，在请求body中上传此二进制内容。媒体图片只支持jpg、png、bmp格式，文件大小不能超过2M。
更多参数、响应详情及错误码请参见商户上传反馈图片接口文档。
# 4. 常见问题
# Q：商户反馈API，查询投诉单列表 API频率是多少？
A：商户反馈API每分钟60次，查询投诉单列表 API频率是每分钟200次。
# Q：商户反馈API，商户传给微信侧的反馈和留言是同步实时处理的吗？
A：是实时的，会直接展示给用户。
# Q：投诉通知回调API中的通知ID，在重复通知的情况下，ID是一致的吗？
A：微信存在重复通知的情况，关于重复通知的客户投诉，通知ID是一致的。
# Q：设置了投诉通知URL，存在用户投诉，但收不到投诉通知的情况，如何解决？
A：请按照以下几点进行排查：
- 请检查回调URL是否能正常公网访问，不能是中文域名，不能是HTTP，必须是HTTPS；
- 请注意回调URL不能携带参数；
- 请检查是否开启了防火墙，如果开启了防火墙，请添加微信支付回调IP (opens new window)；
- 请检查设置通知URL的商户号与投诉订单的商户号是否为同一个；
- APIv3密钥没有设置，设置路径：【微信商户平台 (opens new window)—>账户设置—>API安全—>设置APIv3密钥】。
