商户查询用户欠款状态

更新时间：2024.11.18

商户通过调用该接口可主动查询微信用户的欠款状态。需要注意的是：如果商户想要正常使用本接口，需要预先登记商户的AppID，以及用户欠款状态回调接口地址。当用户欠款状态发生变化时，如果商户与该用户存在处于已签约状态的合约，则校园轻松付会向该回调接口地址主动发送用户欠款状态，商户可以接收回调通知感知用户欠款状态变化；考虑到由于网络等问题可能导致校园轻松付的回调通知无法正确送达回调接口，商户也可以主动使用本接口进行查询。

接口说明

支持商户：【普通服务商】

请求方式：【GET】/v3/eduschoolpay/users/{openid}/debt-state

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

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

请求参数

Header HTTP头参数

Authorization 　必填　string

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

Accept 　必填　string

请设置为application/json

path 路径参数

openid 　必填 string(128)

【商户AppID下的用户标识】OpenID是由微信生成的，代表某个微信用户在AppID下的唯一标识。相同微信用户，AppID不同，则生成的OpenID不同。请注意：调用该接口传入的OpenID应当与商户在校园轻松付登记的AppID对应。如果传入的OpenID不合法或者与登记的AppID不对应，则可能出现：1、查询报错；2、查询返回的OpenID与请求上传的OpenID不一致。

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/eduschoolpay/users/oUpF8uMuAJOM2pxb1Q/debt-state \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数

200 OK

appid 　必填 string(32)

【商户AppID】微信公众平台（mp.weixin.qq.com）为商户分配的公众账号ID，与商户号存在绑定关系。如果是服务商模式接入则为服务商商户号绑定的AppID；如果是直连商户模式接入则为直连商户号绑定的AppID。本AppID为商户在申请接入校园轻松付时所提供的AppID。

openid 　必填 string(128)

【商户AppID下的用户标识】使用字段AppID生成的用户唯一标识，与返回字段AppID有对应关系。

state 　必填 string

【用户状态】根据校园轻松付风控规则，当用户在校园轻松付产品中欠款超过一定限制后，会处于无法扣款的状态，直到用户归还欠款。可选状态：

可选取值：

NORMAL: 根据校园轻松付风控规则，现在可扣款

FORBIDDEN: 根据校园轻松付风控规则，拒绝该用户扣款

debt_count 　必填 integer

【当前用户欠款笔数】用户在校园轻松付中尚未归还的欠款笔数。
用户使用校园轻松付进行消费时，如果微信账户上可用的付款方式均没有足够的余额完成支付，会由微信支付出资对该笔订单进行垫付。这次垫付即会产生一笔用户向微信支付的欠款，直到用户对该笔欠款进行归还。

update_time 　必填 string(32)

【用户欠款状态更新时间】使用rfc3339所定义的格式，即为YYYY-MM-DDThh:mm:ss+TIMEZONE

应答示例

200 OK

1{
2  "appid" : "wx8888888888888888",
3  "openid" : "oUpF8uMuAJOM2pxb1Q",
4  "state" : "NORMAL",
5  "debt_count" : 2,
6  "update_time" : "2017-08-26T09:43:39+08:00"
7}
8

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	INVALID_REQUEST	用户信息有误，请检查OpenID	使用正确的微信OpenID重试
400	INVALID_REQUEST	商户未登记AppID	要正常使用本接口，需要商户预先登记AppID与用户欠款信息回调AppID。请登记后重试。
429	RATELIMIT_EXCEEDED	达到调用速率限制	接口调用频率过快，请降低请求频率
500	SYSTEM_ERROR	出现内部服务器错误	5开头的错误码均为系统错误，请使用相同的参数稍后重试

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服