查询控制单

更新时间:2025.09.09
||

根据外部单号查询管控单、解管单。
管控单:未解管时支持长期查询,解管后支持1年查询。
解管单:支持1年查询。
限频:200/分钟

接口说明

支持商户:【普通商户】

请求方式:【GET】/v3/aggracct-bc/wb-channel/control-orders/{out_request_no}

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

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

请求参数

Header  HTTP头参数

 Authorization  必填 string

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


 Accept  必填 string

请设置为application/json


path  路径参数

 out_request_no  必填   string

【微众管控\解管单号】 需与控制单类型保持一致


query  查询参数

 control_type  必填   string

【控制单类型】 管控\解管

可选取值

  • PUNISH:  管控

  • RECOVER:  解管


 mchid  必填   string

【目标管控\解管商户号】 需与控制单类型保持一致

请求示例

curl
Java
Go

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/aggracct-bc/wb-channel/control-orders/out_request_no_example?control_type=PUNISH&mchid=mchid_example \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数
折叠全部参数

200 OK

 control_scene  必填   string

【控制场景】 控制场景

可选取值

  • PUNISH:  管控

  • RECOVER:  解管


 punish_order  选填   object

【管控单】 控制场景为管控时返回

属性

 wxpay_punish_no  必填   string

【微信管控单号】 微信管控单号


 out_request_no  必填   string

【微众管控单号】 微众管控单号


 mchid  必填   string

【目标下管商户号】 目标下管商户号


 punish_scene  必填   integer

【管控场景】 微众事先在管控系统登记好的场景ID


 punish_rule_version  必填   integer

【管控场景规则版本号】 管控场景对应的业务规则发生变化后,规则版本号加1


 punish_reason  选填   string

【管控原因】 仅支持UTF8可见字符。微众管控原因的具体描述,用于后续产品分析对账。例如“xxx接口核验xxx字段不通过”。


 punish_start_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秒。


 punish_end_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秒。


 punish_accept_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秒。


 punish_finish_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秒。


 punish_state  必填   string

【管控状态】 管控单的状态

可选取值

  • EXECUTING:  执行中

  • SUCCESS:  执行成功

  • FAILED:  执行失败


 effect_state  选填   string

【生效状态】 这条管控当前是否生效或已解管,管控单状态为执行成功才返回。

可选取值

  • ACTIVE:  管控中

  • RECOVERED:  已解管


 control_action  选填   array[string]

【管控方案】 微信支付侧基于管控场景对商户号发起的管控,枚举值: 不可收款,不可提现,不可付款,不可退款,关闭商户注销

可选取值

  • DISABLE_RECEIVE:  不可收款

  • DISABLE_WITHDRAWAL:  不可提现

  • DISABLE_PAY:  不可付款

  • DISABLE_REFUND:  不可退款

  • DISABLE_CLOSE_MERCHANT:  关闭商户注销


 error_message  选填   string

【执行失败错误信息】 系统执行失败的时候返回的错误信息


 error_code  选填   string

【执行失败错误码】 系统执行失败的时候返回的错误码


 recover_order  选填   object

【解管单】 控制场景为解管时返回

属性

 wxpay_recover_no  必填   string

【微信解管单号】 微信解管单号


 out_request_no  必填   string

【微众解管单号】 解管时微众传入的外部单号


 related_wxpay_punish_no  必填   string

【关联微信管控单号】 对应管控时的微信单号


 mchid  必填   string

【目标解管商户号】 微信商户号


 punish_scene  必填   string

【管控场景】 微众事先登记的管控场景ID


 punish_rule_version  必填   string

【管控场景规则版本号】 管控场景对应的业务规则发生变化后,规则版本号加1


 recover_accept_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秒。


 recover_finish_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秒。


 recover_state  必填   string

【解管状态】 解管单的状态

可选取值

  • EXECUTING:  执行中

  • SUCCESS:  执行成功

  • FAILED:  执行失败


 recover_reason  必填   string

【解管原因】 解管原因


 error_message  选填   string

【执行失败错误信息】 系统执行失败的时候返回的错误信息


 error_code  选填   string

【执行失败错误码】 系统执行失败的时候返回的错误码

应答示例

200 OK

1{
2  "control_scene" : "PUNISH",
3  "punish_order" : {
4    "wxpay_punish_no" : "example_wxpay_punish_no",
5    "out_request_no" : "example_out_request_no",
6    "mchid" : "example_mchid",
7    "punish_scene" : 1,
8    "punish_rule_version" : 1,
9    "punish_reason" : "example_punish_reason",
10    "punish_start_time" : "2015-05-20T13:29:35+08:00",
11    "punish_end_time" : "2015-05-20T13:29:35+08:00",
12    "punish_accept_time" : "2015-05-20T13:29:35+08:00",
13    "punish_finish_time" : "2015-05-20T13:29:35+08:00",
14    "punish_state" : "EXECUTING",
15    "effect_state" : "ACTIVE",
16    "control_action" : [
17      "DISABLE_RECEIVE"
18    ],
19    "error_message" : "example_error_message",
20    "error_code" : "example_error_code"
21  },
22  "recover_order" : {
23    "wxpay_recover_no" : "example_wxpay_recover_no",
24    "out_request_no" : "example_out_request_no",
25    "related_wxpay_punish_no" : "example_related_wxpay_punish_no",
26    "mchid" : "example_mchid",
27    "punish_scene" : "example_punish_scene",
28    "punish_rule_version" : "example_punish_rule_version",
29    "recover_accept_time" : "2015-05-20T13:29:35+08:00",
30    "recover_finish_time" : "2015-05-20T13:29:35+08:00",
31    "recover_state" : "EXECUTING",
32    "recover_reason" : "example_recover_reason",
33    "error_message" : "example_error_message",
34    "error_code" : "example_error_code"
35  }
36}
37

 

错误码

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

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

404

NOT_FOUND

控制单不存在

请检查传入的微众管控\解管单号是否正确

404

NOT_FOUND

目标商户号不存在

请检查目标商户号是否正确

 

元宝AI
反馈
目录
置顶