6.3 用户余额扣除接口

优质

小牛编辑

123浏览

2023-12-01

接口说明

该接口由开发者开放给变现猫，变现猫进行调用

当用户发起余额支付请求后，变现猫将会创建一个订单，然后发起该用户的余额扣除请求给开发者。

这个请求会包含用户id，变现猫订单号，扣除的余额数等信息。开发者收到该请求后对签名进行校验。校验通过后请自行在自己系统中创建订单，并记录请求中的相关信息，同时执行用户余额扣除动作。

如果扣除成功，写入成功的参数和开发者系统的订单号，返回这个响应给变现猫。

如果扣除失败，写入失败的参数，并带上失败原因（例如：余额不足）。变现猫收到失败响应后会将这个订单标记为失败，并转告用户失败原因。

扣余额行为可能会发生超时的情况，对于这种情况，变现猫会将订单标记为失败，并进行失败通知。

接口地址：在开发者后台接口配置模块配置(URL以http://开头)

示例：http://www.xxx.com/api/deductAppBalanceApi.json

请求方式：POST

输入参数：

参数	是否必须	参数类型	限制长度	参数说明
appUid	yes	string	255	app用户id
appKey	yes	string	255	接口appKey，应用的唯一标识
balance	yes	number数字	20	本次订单扣除的余额
timestamp	yes	string	20	服务器当前时间，1970-01-01开始的时间戳，毫秒为单位。
description	yes	string	255	本次余额消耗的描述(请用utf-8进行URL解码，防止中文乱码,javaURL编解码详见http://blog.csdn.net/u011627980/article/details/50911249)
orderNum	yes	string	255	变现猫订单号(请记录到数据库中)
sign	yes	string	255	MD5签名,将URL中每个参数值和appSecret（appSecret在开发者后台接口配置处可查看密钥）按照参数名称升序，拼接然后md5转码详见MD5签名规则https://www.xnip.cn/doc/RV0OpbQJLtmd5.html）

响应参数：

参数	是否必须	参数类型	限制长度	参数说明
status	yes	string	255	查询状态，回复ok或者fail
errorMessage	no	string	255	出错原因(请用utf-8进行URL编码，防止中文乱码javaURL编解码详见http://blog.csdn.net/u011627980/article/details/50911249)
appOrderNum	yes	string	255	开发者的订单号(变现猫会判断该订单号的唯一性，注意区分测试和正式对接时的订单号，以免重复)

请按JSON格式返回结果。

响应示例：

成功：

{
 'status': 'ok',
 'errorMessage': '',
 'appOrderNum': '20161011192133033
}

失败：

{
 'status': 'fail',
 'errorMessage': '失败原因'
}

扣余额超时处理方式：

变现猫向开发者发起扣余额请求时，变现猫设置超时时间为10秒，由于开发者服务器响应过慢，或者网络异常等原因，可能会出现超时情况。针对超时情况，变现猫将该订单标记为失败，并向开发者发出失败通知。如果开发者已经扣余额成功了，当收到通知时，需要对用户余额进行回滚。

因为扣余额请求超时，变现猫并没有收到开发者的订单号，因此在发送失败通知时，不会携带orderNum数据。开发者在接受变现猫通知时，请以变现猫订单号orderNum进行处理，而不要根据appOrderNum进行处理！