查询投诉单列表

更新时间:2025.09.02

商户可通过调用此接口,查询指定时间段的所有用户投诉信息,以分页输出查询结果。对于服务商、渠道商,可通过调用此接口,查询指定特约商户号下的投诉信息,若不指定,则查询的是名下所有特约商户投诉信息。

接口说明

支持商户:【普通服务商】 【从业机构(银行)】 【从业机构(支付机构)】 【渠道商】 【清算机构】

请求方式:【GET】/v3/merchant-service/complaints-v2

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


query  查询参数

 limit  选填   integer

【分页大小】 设置该次请求返回的最大投诉条数,范围[1,50]


 offset  选填   integer

【分页开始位置】 该次请求的分页开始位置,从0开始计数,例如offset=10,表示从第11条记录开始返回。


 begin_date  必填   string(10)

【开始日期】 投诉发生的开始日期。注意,查询日期跨度不超过30天


 end_date  必填   string(10)

【结束日期】 投诉发生的结束日期。注意,查询日期跨度不超过30天


 complainted_mchid  选填   string(64)

【被诉商户号】 投诉单对应的被诉商户号。当服务商或渠道商查询指定子商户的投诉信息时按需传入,不传则可以查询名下所有子商户的投诉

请求示例

curl
Java
Go

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/merchant-service/complaints-v2?limit=5&offset=10&begin_date=2019-01-01&end_date=2019-01-01&complainted_mchid=1900012181 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数
折叠全部参数

200 OK

 data  选填   array[object]

【用户投诉信息详情】 用户投诉信息详情

属性

 complaint_id  必填   string(64)

【投诉单号】 投诉单对应的投诉单号


 complaint_time  必填   string(32)

【投诉时间】 投诉时间


 complaint_detail  必填   string(300)

【投诉详情】 投诉的具体描述


 complaint_state  必填   string(30)

【投诉单状态】 标识当前投诉单所处的处理阶段,具体状态如下所示:
PENDING-待处理
PROCESSING-处理中
PROCESSED-已处理完成


 complainted_mchid  必填   string(64)

【被诉商户号】 当服务商或渠道商查询时返回,具体的子商户标识。


 payer_phone  选填   string(512)

【投诉人联系方式】 投诉人联系方式。该字段已做加密处理,具体解密方法详见如何使用API证书解密敏感字段


 complaint_order_info  选填   array[object]

【投诉单关联订单信息】 投诉单关联订单信息

属性

 transaction_id  必填   string(64)

【微信订单号】 投诉单关联的微信订单号


 out_trade_no  必填   string(64)

【商户订单号】 投诉单关联的商户订单号


 amount  必填   integer

【订单金额】 订单金额,单位(分)


 complaint_full_refunded  必填   boolean

【投诉单是否已全额退款】 投诉单下所有订单是否已全部全额退款


 incoming_user_response  必填   boolean

【是否有待回复的用户留言】 投诉单是否有待回复的用户留言


 user_complaint_times  必填   integer

【用户投诉次数】 用户投诉次数。用户首次发起投诉记为1次,用户每有一次继续投诉就加1


 complaint_media_list  选填   array[object]

【投诉资料列表】 用户上传的投诉相关资料,包括图片凭证等

属性

 media_type  必填   string

【媒体文件业务类型】 媒体文件对应的业务类型

可选取值

  • USER_COMPLAINT_IMAGE:  用户提交投诉时上传的图片凭证

  • OPERATION_IMAGE:  用户、商户、微信支付客服在协商解决投诉时,上传的图片凭证


 media_url  必填   array[string(512)]

【媒体文件请求url】 微信返回的媒体文件请求url,详细调用请参考:图片请求接口
示例 "https://api.mch.weixin.qq.com/v3/merchant-service/images/xxxxx" 中 "xxxxx" 代表媒体文件标识 ID(meida_id)


 problem_description  必填   string(256)

【问题描述】 用户发起投诉前选择的faq标题(2021年7月15日之后的投诉单均包含此信息)


 problem_type  选填   string

【问题类型】 问题类型为申请退款的单据是需要最高优先处理的单据

可选取值

  • REFUND:  申请退款

  • SERVICE_NOT_WORK:  服务权益未生效

  • OTHERS:  其他类型


 apply_refund_amount  选填   integer

【申请退款金额】 仅当问题类型为申请退款时, 有值, (单位:分)


 user_tag_list  选填   array[string]

【用户标签列表】 用户标签列表

可选取值

  • TRUSTED:  此类用户满足极速退款条件

  • HIGH_RISK:  高风险投诉,请按照运营要求优先妥善处理


 service_order_info  选填   array[object]

【投诉单关联服务单信息】 

属性

 order_id  选填   string(128)

【微信支付服务订单号】 微信支付服务订单号,每个微信支付服务订单号与商户号下对应的商户服务订单号一一对应


 out_order_no  选填   string(128)

【商户服务订单号】 商户系统内部服务订单号(不是交易单号),与创建订单时一致


 state  选填   string

【支付分服务单状态】 此处上传的是用户发起投诉时的服务单状态,不会实时更新

可选取值

  • DOING:  服务订单进行中

  • REVOKED:  服务订单已取消

  • WAITPAY:  服务订单待支付

  • DONE:  服务订单已完成


 additional_info  选填   object

【补充信息】 用在特定行业或场景下返回的补充信息

属性

 type  选填   string

【补充信息类型】 补充信息类型

可选取值

  • SHARE_POWER_TYPE:  充电宝投诉相关行业


 share_power_info  选填   object

【充电宝投诉相关信息】 当type为充电宝投诉相关时有值

属性

 return_time  选填   string

【归还时间】 遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。


 return_address_info  选填   object

【归还地点信息】 归还地点信息,选填

属性

 return_address  选填   string(256)

【归还地点】 归还地点


 longitude  选填   string(32)

【归还地点经度】 经度,字符串,范围为-180~180,负数表示西经。使用GCJ-02坐标系


 latitude  选填   string(32)

【归还地点纬度】 纬度,字符串,范围为-90~90,负数表示南纬。使用GCJ-02坐标系


 is_returned_to_same_machine  选填   boolean

【是否归还同一柜机】 用户声明是否将充电宝归还至与借取时同一柜机


 in_platform_service  选填   boolean

【是否在平台协助中】 标识当前投诉单是否正处在平台协助流程中。注:在协助期间由微信支付客服为用户服务,期间商户向用户发送的留言用户不可见


 need_immediate_service  选填   boolean

【是否需即时服务用户】 因用户诉求紧急度、用户界面差异等因素,部分投诉单建议商户更即时地响应用户诉求。如此处标识为“是”,建议商户提升服务时效,给用户带来更好的体验


 is_agent_mode  选填   boolean

【是否是智能体投诉】 对接商家智能体的商户,用户针对某笔订单下的智能服务质量产生投诉,商户需要结合投诉内容,在智能体服务内更加及时、妥善地服务用户


 limit  必填   integer

【分页大小】 设置该次请求返回的最大投诉条数,范围[1,50]


 offset  必填   integer

【分页开始位置】 该次请求的分页开始位置,从0开始计数,例如offset=10,表示从第11条记录开始返回。


 total_count  选填   integer

【投诉总条数】 投诉总条数,当offset=0时返回

应答示例

200 OK

1{
2  "data" : [
3    {
4      "complaint_id" : "200201820200101080076610000",
5      "complaint_time" : "2015-05-20T13:29:35.120+08:00",
6      "complaint_detail" : "反馈一个重复扣费的问题",
7      "complaint_state" : "PENDING",
8      "complainted_mchid" : "1900012181",
9      "payer_phone" : "18500000000",
10      "complaint_order_info" : [
11        {
12          "transaction_id" : "4200000404201909069117582536",
13          "out_trade_no" : "20190906154617947762231",
14          "amount" : 3
15        }
16      ],
17      "complaint_full_refunded" : true,
18      "incoming_user_response" : true,
19      "user_complaint_times" : 1,
20      "complaint_media_list" : [
21        {
22          "media_type" : "USER_COMPLAINT_IMAGE",
23          "media_url" : [
24            "https://api.mch.weixin.qq.com/v3/merchant-service/images/xxxxx"
25          ]
26        }
27      ],
28      "problem_description" : "不满意商家服务",
29      "problem_type" : "REFUND",
30      "apply_refund_amount" : 10,
31      "user_tag_list" : [
32        "TRUSTED"
33      ],
34      "service_order_info" : [
35        {
36          "order_id" : "15646546545165651651",
37          "out_order_no" : "1234323JKHDFE1243252",
38          "state" : "DOING"
39        }
40      ],
41      "additional_info" : {
42        "type" : "SHARE_POWER_TYPE",
43        "share_power_info" : {
44          "return_time" : "2015-05-20T13:29:35+08:00",
45          "return_address_info" : {
46            "return_address" : "广东省深圳市南山区海天二路南山区后海腾讯滨海大厦(海天二路西)",
47            "longitude" : "113.93535488533665",
48            "latitude" : "22.52305518747831"
49          },
50          "is_returned_to_same_machine" : false
51        }
52      },
53      "in_platform_service" : true,
54      "need_immediate_service" : true,
55      "is_agent_mode" : true
56    }
57  ],
58  "limit" : 5,
59  "offset" : 10,
60  "total_count" : 1000
61}
62

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

 

元宝AI
反馈
目录
置顶