第三章 模块接口(2) - 发放、充值
## 综合服务云平台 - API功能模块接口明细
## 版本更新记录
|修订日期|修订内容|修订人|
|-|-|-|
|2020.05.21|v1.0发布|彭晓伟|
|2020.05.21|新增接口：1.提交订单,2确认发放,3.发放结果查询接口,4.公司可开票类型，主体查询接口|彭晓伟|
|2020.06.08|新增接口：1.充值接口，2.余额查询|彭晓伟|
|2020.06.19|新增接口：1.充值成功异步回调，2.发放成功异步回调 |彭晓伟|
## 接口时序图
## 4.结算订单管理
## 4.1 提交订单接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/bill/submitBill
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|payeeName|收款人姓名|String|是||
|payeeAccount|收款账户|String|是||
|payeeIdCard|收款人身份证号码|String|是||
|amount |收款金额|String|是|收款金额必须为数字|
|payeePhone|收款人手机号|String|否|该参数用于用户接收到款短信|
|thirdOrderId|商户订单号|String|是|商户自己生成，不可重复提交|
|thirdBizOrderId|第三方业务订单ID|String|否|该参数为商户自己的业务订单号，通过该订单号能够查询该笔金额来源明细|
|payType|支付类型|int|否|支付类型该参数值填写支付类型对应数字即可 0:银行卡、1：支付宝|
|mainstayId|主体ID|Long|是|该参数由==4.4查询发票信息与主体信息接口==可获的|
|invoiceCode|发票编码|String|是|该参数由==4.4查询发票信息与主体信息接口==可获的|
|remark|备注|String|否|备注字数不可超过32个字符|
|transName|转账附言|String|否|备注字数不可超过20个字符|
#### 注意：
转账附言字段：如需要配置请联系相关商务人员申请配置；
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billNo| 订单号|String|是||
|itemStatus| 发放平台订单状态|int|是|发放结果码对照表[2. 结算明细订单状态状态码](https://easydoc.xyz/doc/63011222/0klm3Gmk/lsNgE5QQ)|
|actualAmount| 结算金额(实际个人所得额)|BigDecimal|是||
|valueAddedTaxAmount|增值税|BigDecimal|是||
|additionalTaxAmount|附加税|BigDecimal|是||
|personIncomeTaxAmount|个税|BigDecimal|是||
|contractTaxAmount|服务费(合同税费)|BigDecimal|是||
|paymentAmount|实际打款金额(需要扣除的费用)|BigDecimal|是||
|failReason|失败原因|String|否||
## 4.2 确认发放接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/bill/sureGrant
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|billNo|订单号|String|是|该值由提交订单接口返回|
|settlementCertUrl|结算证明|String|否|该参数由[7.上传文件接口上传完证明返回的链接](https://easydoc.xyz/doc/63011222/0klm3Gmk/DtZ29fva)|
>d注意：
>settlementCertUrl(结算证明)：是根据商户后台配置判断的
>直营模式：
>（1）结算前配置：结算时必填，开票申请时就非必填
>（2）开票前配置：开票申请时必填，结算时非必填
>众包模式：默认是不需要上传结算证明的
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 第三方订单号|String| 是|生成订单接口的thirdOrderId字段的值|
|itemStatus| 发放结果状态|int| 是|详情请参考 [2. 结算明细订单状态状态码](https://easydoc.xyz/doc/63011222/0klm3Gmk/lsNgE5QQ)|
|returnMsg| 返回信息|String|是| ||
|billNo| 订单号|String|是| ||
## 4.3 结算结果查询接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/bill/queryResult
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|无参数名称|需要查询的商户订单号|Array|是|例如：[商户订单号1,商户订单号2]|
>d 该接口参数无需参数名称只需将商户订单号拼接处json数组即可
示例：String data = [\"xxx\",\"xxx\"... ,\"xxx\"];
一次性最多查询10条记录
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billNo| 平台订单号|String |是|平台订单号|
|thirdOrderNo| 商户订单号|String |是|商户第三方订单号|
|itemStatus| 结果状态|int| 是|详情请参考 [2. 结算明细订单状态状态码](https://easydoc.xyz/doc/63011222/0klm3Gmk/lsNgE5QQ)|
|amount|结算金额|String|是|提交的金额|
|paymentTime|发放时间|String|否|确认发放后才有，确认结算时间|
|reason| 失败原因|String|是|支付失败才会有该值|
|personIncomeTaxAmount|个税|String|否|直营模式才会有该值|
|valueAddedTaxAmount|增值税|String|否|直营模式才会有该值|
|additionalTaxAmount|附加税|String|否|直营模式才会有该值|
|contractTaxAmount|服务费|String|否|直营模式才会有该值|
>d该发放结果data解密后为List 集合json字符串。
结果示例
[{"billNo":"xxx","thirdOrderNo":"xxx","status":1,"itemStatus":1,"amount":"100.0","paymentTime":"xxx","reason":"xxxx","returnMsg":"xx","personIncomeTaxAmount":"0.01","valueAddedTaxAmount":"0.01","additionalTaxAmount":"0.01","contractTaxAmount":"0.01"},...]
## 4.4 查询发票信息与主体信息接口
>d 通过该接口可获取公司的可开发票列表，以及所拥有主体列表,无需频繁请求。请求到之后保存自己库即可。当签署主体信息有变更。或者发票内容有调整重新请求接口即可。
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/queryInvoices
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|无参数||||该接口无需参数|
#### 响应参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|name| 主体名称| String|是|主体名称|
|mainstayId| 主体ID|int| 是|主体ID|
|taxRate| 税率|BigDecimal| 是||
|qsPattern|轻税模式|int| 是|0:直营模式,1:分包模式|
|qsModel|轻税方式|int| 是|0:税前，1:税后|
|invoiceOpResponseList| 发票列表| ||发票列表为List数组|
|invoiceCode| 发票列表里面属性值发票编码|String| 是|invoiceOpResponseList里面属性|
|name| 发票列表里面属性值发票名称|String| 是|invoiceOpResponseList里面属性|
解密结果示例如下：
```json
[{
"invoiceOpResponseList": [{
"invoiceCode": "XXJSFWJSFWF1", //发票编码
"name": "信息技术服务,技术服务费" //发票内容
}, {
"invoiceCode": "XXJSFWJSZXFWF2",
"name": "信息技术服务,技术咨询服务费"
}],
"mainstayId": 1, //主体ID
"name": "xxx", //主体名称
"taxRate":0.050, //税率
"qsPattern":0, //轻税模式 0:直营模式,1:分包模式
"qsModel":0 //轻税方式 0:税前，1:税后
}, {
"invoiceOpResponseList": [{
"invoiceCode": "JZZXFWZXFWF19",
"name": "鉴证咨询服务,咨询服务费"
}, {
"invoiceCode": "JZZXFWQYGLZXF20",
"name": "鉴证咨询服务,企业管理咨询费"
}],
"mainstayId": 2,
"name": "xxx",
"taxRate" : 0.050,
"qsPattern":0,
"qsModel":0
}]
```
## 4.5 发放成功异步回调
>d 该接口需要第三方自行编写提供接口到发放平台回调成功必须返回success不然会重复回调 接口编写示例跟5.3 充值回调接口说明一致
解密结果示例如下：
```json
{"billNo":"xxx","thirdOrderNo":"xxx","status":1,"itemStatus":1,"amount":"100.0","paymentTime":"xxx","reason":"xxxx","returnMsg":"xx","personIncomeTaxAmount":"0.01","valueAddedTaxAmount":"0.01","additionalTaxAmount":"0.01","contractTaxAmount":"0.01"}
```
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billNo| 平台订单号|String |是|平台订单号|
|thirdOrderNo| 商户订单号|String |是|商户第三方订单号|
|itemStatus| 结果状态|int| 是|详情请参考 [2. 结算明细订单状态状态码](https://easydoc.xyz/doc/63011222/0klm3Gmk/lsNgE5QQ)|
|amount|结算金额|String|是|提交的金额|
|paymentTime|发放时间|String|否|确认发放后才有，确认发放时间|
|reason| 失败原因|String|是|支付失败才会有该值|
|personIncomeTaxAmount|个税|String|否|直营模式才会有该值|
|valueAddedTaxAmount|增值税|String|否|直营模式才会有该值|
|additionalTaxAmount|附加税|String|否|直营模式才会有该值|
|contractTaxAmount|服务费|String|否|直营模式才会有该值|
## 5. 充值管理
## 5.1 充值接口（个体工商户集群众包模式）
#### 开发环境：https://pay-dev.lx-rhino.com
#### 生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/balance/recharge
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|mainstayId|主体ID|String|是||
|amount|充值金额|String|是||
|bankVoucherFile|充值银行回执单|String|否|该参数为通过[7.上传文件接口上传](https://easydoc.xyz/doc/63011222/0klm3Gmk/DtZ29fva)将文件上传后返回的值|
|remarks|备注|String|否||
|thirdRechargeNo|第三方充值单号|String|是||
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdRechargeNo| 第三方充值单号| String|是||
|entryAmount| 打款金额|String|是||
|rechargeAmount| 实际充值到账金额（扣除税费）|String|是| ||
|contractTaxRate| 税率|String|是| ||
|contractTaxAmount| 税费|String|是| ||
## 5.2 余额查询接口
>d当请求商户业务模式为直营模式时，只返回商户余额
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/balance/query
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
>d该接口无需请求参数即可查询余额。
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|banlance| 余额|String|是||
|mainstayName| 主体名称|String|是||
>d该响应参数data字段解密后为即为余额。
解密结果示例
[{"banlance":"11.40","mainstayName":"安吉"}]
## 5.3 充值成功异步回调
>d 该接口需要第三方自行编写提供接口到发放平台回调成功必须返回success不然会重复回调
>d 该接口需要第三方自行编写提供接口到发放平台 接口编写示例如下。
```java
@PostMapping("signCallBack")
@ResponseBody
public String signCallBack(HttpServletRequest request, @RequestBody String data){
String publicKey = "该公钥由发放平台提供发放到贵司邮箱";
//解密
String decode = RSAHelper.decryptByPublicKey(data, publicKey);
/*贵公司处理业务逻辑*/
return "success";
}
```
解密工具类在 [JAVA_DEMO](https://gitee.com/xinfudblog/lxapi_java_demo) 的 RSAHelper 类中
>d
> 1.贵司写完后提供到接口url给发放平台即可。回调成功必须返回success，不然会重复回调，至多重试8次。
> 2.每次回调的间隔时间2N次方分钟，比如第一次回调间隔时间为2分钟，第二次就为4分钟，依次往后推，最多重试8次；
postman中模拟接口是否正常接收数据如下操作
解密结果示例如下：
```json
{"auditStatus":"2","rechargeAmount":"12.01","thirdRechargeNo":"xxxxx","entryTime":"2019-07-05 23:41:45","entryAmount":"12.01","contractTaxAmount":"12.01","contractTaxRate":"12.01"}";
```
|参数名称| 参数含义| 数据类型|是否必有| 参数备注|
|-|-|-|-|-|
|auditStatus| 充值审核状态|int| 是||
|rechargeAmount| 充值金额|BigDecimal| 是||
|thirdRechargeNo| 第三方充值单号|String| 是||
|entryTime| 充值时间 |String| 是||
|entryAmount| 入账金额|BigDecimal| 是||
|contractTaxAmount| 合同税费|BigDecimal| 是||
|contractTaxRate| 合同税率|BigDecimal| 是||
## 5.4 个体工商户计算综合税费接口（暂停使用）
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
~~#### 接口地址：/open/api/v1/selfRegistered/calculateTax/{token}~~（此接口暂时关闭，请调用5.6个体户计算综合税费接口）
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|amount|提交金额|BigDecimal|是||
|mainstayId|主体id|Integer|是||
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|invoiceAmount|开票金额|BigDecimal|是
|personIncomeTaxAmount|个税|BigDecimal|是
|valueAddedTaxAmount|增值税|BigDecimal|是
|additionalTaxAmount|附加税|BigDecimal|是
|serviceAmount|服务费|BigDecimal|是
|incomeAmount|到账金额|BigDecimal|是
## 5.5 取消订单接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/bill/cancel
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数类型|参数含义|是否必填|参数备注|
|-|-|-|-|-|
|billNo|String|平台返回的提交结算订单号|是||
|reason|String|取消原因(取消原因字段限制不超过30字)|否||
#### 接口响应参数data字段解密后的参数说明：
>d 该接口响应参数中无响应data字段 ,success 等于true代表取消成功，false 代表失败 errorMessage中有错误信息反馈
## 5.6 个体工商户计算综合税费接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/selfRegistered/calculateTax
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|amount|提交金额|BigDecimal|是||
|mainstayId|主体id|Integer|是||
|idCard|个体户身份证|String|是||
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|invoiceAmount|开票金额|BigDecimal|是
|personIncomeTaxAmount|个税|BigDecimal|是
|valueAddedTaxAmount|增值税|BigDecimal|是
|additionalTaxAmount|附加税|BigDecimal|是
|serviceAmount|服务费|BigDecimal|是
|incomeAmount|到账金额|BigDecimal|是
## 5.7 个体工商户可结算金额查询
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/qs/qsSelfEmployedSettledAmountQuery
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCard|个体户身份证号|String|是||
|mainstayId|注册地ID|String|是|该参数值由4.4 查询发票信息与主体信息接口|
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|name|个体户姓名|String|是|例：张三|
|idCard|个体户身份证号|String|是|例：410422199405051167|
|thisMonthSettledAmount|本月已结算金额|String|是|例：0|
|thisMonthSurplusOfAmount|本月剩余可结算金额|String|是|例：400000|
|surplusOfInvoiceAmount|剩余可开票金额|String|是|例：4950000|
#### 字段解释：
（1）剩余可开票金额：指的是记录个体工商户剩余可开发票的金额，由于个体工商户开票年度总金额的限制的原因；开票年度计算方式，个体工商户连续12月开票金额不得超过495W，例如：从2021年3月份往前推12个月的开票金额不得超过495W，4月份依次类推。例如：495W - 2020年4月份到2021年的3月份之前开票的金额 = 剩余可开票金额；
## 5.8 个体户可结算金额查询（批量）
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/qs/qsSelfEmployedSettledAmountBatchQuery
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCards|个体户身份证号|List<String>|是||
|mainstayId|注册地ID|String|是|该参数值由4.4 查询发票信息与主体信息接口|
#### 接口响应参数说明：
>d 1. 响应的data是一个数组
> 2. 批量查询最多入参查询人数为100人
```json
[
{
"name":"张三",
"idCard":"410422199405051167",
"thisMonthSettledAmount":0,
"thisMonthSurplusOfAmount":400000,
"surplusOfInvoiceAmount":4950000,
"queryStatus":true,
"failReason":"xxx",
},
...
]
```
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|name|个体户姓名|String|是|例：张三|
|idCard|个体户身份证号|String|是|例：410422199405051167|
|thisMonthSettledAmount|本月已结算金额|BigDecimal|是|例：0|
|thisMonthSurplusOfAmount|本月剩余可结算金额|BigDecimal|是|例：400000|
|surplusOfInvoiceAmount|剩余可开票金额|BigDecimal|是|例：4950000|
|queryStatus|查询状态|Boolean|是|个体户查询状态：成功返回true，失败返回false|
|failReason|查询失败原因|String|否|个体户查询失败时此字段会返回失败原因|
#### 字段解释：
（1）剩余可开票金额：指的是记录个体工商户剩余可开发票的金额，由于个体工商户开票年度总金额的限制的原因；开票年度计算方式，个体工商户连续12月开票金额不得超过495W，例如：从2021年3月份往前推12个月的开票金额不得超过495W，4月份依次类推。例如：495W - 2020年4月份到2021年的3月份之前开票的金额 = 剩余可开票金额；