2.结算接口
## 1 .确认式结算接口
说明：确认式结算接口为商户提供订单前置信息校验，商户可通过前置调用提交接口验证该笔订单是否可结算，同时商户可对提交后校验成功订单做二次审核后，决定是否继续执行资金结算。
#### 调用时序图
### 1.1 结算单提交接口
#### 接口地址：
/open/api/v1/qs/bill/submitBill
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|payeeName|收款人姓名|String|是||
|payeeIdCard|收款人身份证号码|String|是||
|payType|账户类型|int|否|0:银行账户1:支付宝账户|
|payeeAccount|收款账号|String|是||
|amount |收款金额|String|是|收款金额必须为数字|
|payeePhone|收款人手机号|String|否|该参数用于用户接收到款短信|
|thirdOrderId|商户订单号|String|是|商户自己生成，不可重复提交|
|thirdBizOrderId|第三方业务订单ID|String|否|该参数为商户自己的业务订单号，通过该订单号能够查询该笔金额来源明细|
|mainstayId|主体ID|Long|是|该参数值可通过《[查询企业合作主体，发票类目等信息](https://easydoc.net/doc/64606353/WRXJG4oL/lH8xS88b#nav_0)》查询|
|invoiceCode|发票编码|String|是|该参数值可通过《[查询企业合作主体，发票类目等信息](https://easydoc.net/doc/64606353/WRXJG4oL/lH8xS88b#nav_0)》查询|
|remark|备注|String|否|备注字数不可超过32个字符|
|transName|转账备注|String|否|备注字数不可超过20个字符|
|taskNo|关联服务编码|String(32)|否|由商户自行评估该提交结算订单是否需要关联服务|
|invoiceClassification|发票类型|int|否|0：增值税电子普通发票，1：增值税专用发票，2：通用电子普通发票，4：增值税电子专用发票，6：数电票（专用发票），7：数电票（普通发票），支持专普混开的商户必填|
|taxPointConf|发票税率|int|否|0：3%，1：1%，支持专普混开的商户必填|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billNo| 订单号|String|是||
|actualAmount| 结算金额|BigDecimal|是|个体户实际到账金额|
|valueAddedTaxAmount|增值税|BigDecimal|是||
|additionalTaxAmount|附加税|BigDecimal|是||
|personIncomeTaxAmount|个税|BigDecimal|是||
|contractTaxAmount|服务费(合同税费)|BigDecimal|是||
|paymentAmount|实际打款金额(需要扣除的费用)|BigDecimal|是||
|itemStatus| SSC平台订单状态|Integer|是|[结算结果状态码](https://easydoc.net/doc/95180784/Ry461Ra3/g5SDIGDl)
|failReason|失败原因|String|否|
### 1.2 结算单确认结算接口
#### 接口地址：
/open/api/v1/qs/bill/sureGrant
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|billNo|订单号|String|是|该值由提交订单接口返回|
|settlementCertUrl|结算证明|String|否|url链接|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 第三方订单号|String| 是|生成订单接口的thirdOrderId字段的值|
|billNo| 订单号|String|是| ||
|itemStatus| 结算结果状态|int| 是|详情请参考[结算结果状态码](https://easydoc.net/doc/95180784/Ry461Ra3/g5SDIGDl)|
|returnMsg|失败原因|String|否||
### 1.3 结算单取消结算接口
#### 接口地址：
/open/api/v1/qs/bill/cancel
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数类型|参数含义|是否必填|参数备注|
|-|-|-|-|-|
|billNo|String|订单号|是|该值由提交订单接口返回|
|reason|String|取消原因|否|取消原因字段限制不超过30字|
#### 接口响应参数data字段解密后的参数说明：
>d 该接口响应参数中无响应data字段 ,success 等于true代表取消成功，false 代表失败 errorMessage中有错误信息反馈
## 2. 即时结算接口
说明：调用即时结算接口商户将订单信息提交后，SSC校验通过将实时进行资金结算。
#### 调用时序图
#### 接口地址：
/open/api/v1/qs/bill/payment
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|thirdOrderId|商户订单号|String|是|商户自己生成，不可重复提交|
|mainstayId|主体ID|Integer|是|该参数值可通过《[查询企业合作主体，发票类目等信息](https://easydoc.net/doc/64606353/WRXJG4oL/lH8xS88b#nav_0)》查询|
|invoiceCode|发票编码|String|是|该参数值可通过《[查询企业合作主体，发票类目等信息](https://easydoc.net/doc/64606353/WRXJG4oL/lH8xS88b#nav_0)》查询|
|payeeName|收款人姓名|String|是||
|payeeIdCard|收款人身份证号码|String|是||
|payType|账户类型|Integer|否| 0:银行账户1:支付宝账户2:微信零钱账户|
|payeeAccount|收款账号|String|是||
|amount |收款金额|String|是|收款金额必须为数字|
|payeePhone|收款人手机号|String|否|该参数用于用户接收到账提醒短信|
|wxAppId|微信多渠道appid|String|否|同一商户有多个微信提现APPID使用，需联系技术沟通|
|thirdBizOrderId|第三方业务订单ID|String|否|该参数为商户自己的业务订单号，通过该订单号能够查询该笔金额来源明细|
|remark|备注|String|否|备注字数不可超过32个字符|
|transName|转账备注|String|否|备注字数不可超过20个字符|
|settlementCertUrl|结算证明|String|否|url链接,最长640字符|
|taskNo|关联服务编码|String(32)|否|由商户自行评估该提交结算订单是否需要关联服务|
|invoiceClassification|发票类型|int|否|0：增值税电子普通发票，1：增值税专用发票，2：通用电子普通发票，4：增值税电子专用发票，6：数电票（专用发票），7：数电票（普通发票），支持专普混开的商户必填|
|taxPointConf|发票税率|int|否|0：3%，1：1%，支持专普混开的商户必填|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billNo|订单号|String|是| ||
|thirdOrderId|商户订单号|String| 是||
|checkStatus|风控校验状态|Integer| 是|-1：校验失败； 1：校验成功；|
|failReason|失败原因|String|否| ||
## 3. 结算结果异步回调
>d 该接口需要第三方自行编写提供接口到SSC平台回调成功必须返回success不然会重复回调 接口编写示例跟5.3 充值回调接口说明一致
解密结果示例如下：
```json
{
"callbackType": "qsPayResult",
"billNo": "QS2022123123123123",
"thirdOrderNo": "zhifu123",
"status": 1,
"itemStatus": 1,
"amount": "100.0",
"paymentTime": "2020-12-12 09:23:12",
"returnMsg": "xx",
"personIncomeTaxAmount": "0.01",
"valueAddedTaxAmount": "0.01",
"additionalTaxAmount": "0.01",
"contractTaxAmount": "0.01",
"realPaymentAmount": "0.01",
"cooperateExpensesAmount": "0.01",
"cooperateExpensesTax": "0.001",
"serviceTax": "0.001",
}
```
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|callbackType|回调类型|String|是|固定返回：qsPayResult|
|billNo| 平台订单号|String |是|平台订单号|
|thirdOrderNo| 商户订单号|String |是|商户第三方订单号|
|itemStatus| 结果状态|int| 是|详情请参考[结算结果状态码](https://easydoc.net/doc/95180784/Ry461Ra3/g5SDIGDl)|
|amount|结算金额|String|是|提交的金额|
|paymentTime|结算时间|String|否|格式：yyyy-MM-dd HH:mm:ss|
|returnMsg| 失败原因|String|是|结算失败才会有该值|
|source|所属业务线|String|是|2：轻税 3：账管家 4:云纳税|
|taxType|征收方式|String|否| 0:累进制 2:定期定额 3:查账征收|
|personIncomeTaxAmount|个税|String|否|直营模式才会有该值|
|valueAddedTaxAmount|增值税|String|否|直营模式才会有该值|
|additionalTaxAmount|附加税|String|否|直营模式才会有该值|
|contractTaxAmount|服务费|String|否|直营模式才会有该值|
|realPaymentAmount|总支付金额|String|否|众包业务线后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额（到账金额）+合作费用|
|cooperateExpensesAmount|合作费用|String|否|众包业务线后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额*合作费率|
|cooperateExpensesTax|合作费率|String|否|众包业务线后置收费模式有值。查询商户是否为后置收费可联系商务。|
|serviceTax|服务费率|String|否|直营模式才会有该值|
## 4. 结算结果查询接口
#### 接口地址：
/open/api/v1/qs/bill/queryResult
#### 请求方式：POST
#### 请求参数说明：
```json
[
"zhifu111",
"zhifu222",
...
]
```
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|无参数名称|需要查询的商户订单号|List<String>|是|最多10个订单号|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billNo| 平台订单号|String |是|平台订单号|
|thirdOrderNo| 商户订单号|String |是|三方订单号|
|~~status~~| 结果状态|int| 是|老字段，已废弃，请对接itemStatus|
|itemStatus| 结果状态|int| 是|详情请参考[结算结果状态码](https://easydoc.net/doc/95180784/Ry461Ra3/g5SDIGDl)|
|amount|结算金额|String|是|提交的金额|
|paymentTime|结算时间|String|否|格式：yyyy-MM-dd HH:mm:ss，确认结算后才有|
|reason| 失败原因|String|是|支付失败才会有该值|
|returnMsg| 失败原因|String|是|老字段，已废弃，请对接reason|
|source|所属业务线|String|是|2：轻税 3：账管家 4:云纳税|
|taxType|征收方式|String|否| 0:累进制 2:定期定额 3:查账征收|
|personIncomeTaxAmount|个税|String|否|直营才会有该值|
|valueAddedTaxAmount|增值税|String|否|直营才会有该值|
|additionalTaxAmount|附加税|String|否|直营才会有该值|
|contractTaxAmount|服务费|String|否|直营才会有该值|
|realPaymentAmount|总支付金额|String|否|众包业务线后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额（到账金额）+合作费用|
|cooperateExpensesAmount|合作费用|String|否|众包业务线后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额*合作费率|
|cooperateExpensesTax|合作费率|String|否|众包业务线后置收费模式有值。查询商户是否为后置收费可联系商务。|
|serviceTax|服务费率|String|否|直营才会有该值|
>d该结算结果data解密后为List 集合json字符串。
结果示例
```json
[
{
"billNo": "xxx",
"thirdOrderNo": "zhifu111",
"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",
"realPaymentAmount": "0.01",
"cooperateExpensesAmount": "0.01",
"cooperateExpensesTax": "0.001",
"serviceTax": "0.001",
},
...
]
```
## 5. 电子回单
### 5.1 电子回单查询
>d 电子回单在支付完成之后，需要一定时间制作，如若需要系统生成好回单自动推送，请调用电子回单回调申请接口
#### 接口地址：
/open/api/v1/qs/bill/voucher/query
#### 请求方式：POST
#### 请求参数说明：
>d 请求确保callbackUrl地址能够用外网正常访问
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|thirdOrderNo|商户订单号|String|是|
|callbackUrl|回调地址|String|否|如果电子回单未生成，将会记录回调地址，等电子回单生成后主动推送，调用此地址，重复提交（相同订单号）视为修改回调地址（入参空地址则不修改），一个订单只会回调一次|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo|商户订单号|String|是||
|status|电子回单状态|Integer|是|-1-未制作（没有提供回调地址）；0-制作中（回单制作完成将主动推送回调地址）；1-制作完成；|
|voucherUrl|电子回单下载地址|String|否|回单制作完成时有值|
### 5.2 电子回单回调接口
#### 请求方式：POST
#### 请求参数说明：
>d 请在正常接收到回调请求后返回小写字符串"success"，否则系统的回调补偿机制将轮询回调
````json
{
"callbackType":"voucher",
"thirdOrderNo":"huidan123",
"status":"1",
"voucherUrl":"https://xxx.xxx.xxx/xxx.png"
}
````
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|callbackType|回调类型|String|是|固定返回：voucher|
|thirdOrderNo|商户订单号|String|是||
|status|电子回单状态|Integer|是|固定返回：1 (制作完成)|
|voucherUrl|电子回单下载地址|String|是||
## 6.个体工商户计算综合税费接口
#### 接口地址：/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|是
## 7. 个体工商户余额查询接口
### 7.1 个体工商户余额查询接口（单个）
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/qs/qsSelfEmployedSettledAmountQuery
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCard|个体户身份证号|String|是||
|mainstayId|注册地ID|String|是|该参数值可通过《[查询企业合作主体，发票类目等信息](https://easydoc.net/doc/64606353/WRXJG4oL/lH8xS88b#nav_0)》查询|
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|name|个体户姓名|String|是|例：张三|
|idCard|个体户身份证号|String|是|例：410422199405051167|
|thisMonthSettledAmount|本月已结算金额|String|是|例：0.00|
|thisMonthSurplusOfAmount|本月剩余可结算金额|String|是|例：400000.00|
|surplusQuarterAmount|季度剩余可开票金额|String|是|例：450000.00|
|surplusYearAmount|自然年剩余可开票金额|String|是|例：1800000.00|
|surplusCumulativeTwelveMonthsAmount|连续12个月剩余可开票金额|String|是|例：4950000.00|
|surplusOfInvoiceAmount|剩余可开票金额|String|是|例：4950000.00;该字段取当前季度、自然年、连续12个月条件中最小剩余可开票金额|
### 7.2 个体工商户余额查询接口（批量）
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/qs/qsSelfEmployedSettledAmountBatchQuery
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCards|个体户身份证号|List<String>|是||
|mainstayId|注册地ID|String|是|该参数值可通过《[查询企业合作主体，发票类目等信息](https://easydoc.net/doc/64606353/WRXJG4oL/lH8xS88b#nav_0)》查询|
#### 接口响应参数说明：
>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|本月已结算金额|String|是|例：0.00|
|thisMonthSurplusOfAmount|本月剩余可结算金额|String|是|例：400000.00|
|surplusQuarterAmount|季度剩余可开票金额|String|是|例：450000.00|
|surplusYearAmount|自然年剩余可开票金额|String|是|例：1800000.00|
|surplusCumulativeTwelveMonthsAmount|连续12个月剩余可开票金额|String|是|例：4950000.00|
|surplusOfInvoiceAmount|剩余可开票金额|String|是|例：4950000.00;该字段取当前季度、自然年、连续12个月条件中最小剩余可开票金额|
|queryStatus|查询状态|Boolean|是|个体户查询状态：成功返回true，失败返回false|
|failReason|查询失败原因|String|否|个体户查询失败时此字段会返回失败原因|
#### 字段解释：
1.‘本月已结算金额’=本月已提交且成功结算的金额；
2.‘本月剩余可结算金额’=本月结算限额-本月已结算金额；月结算限额默认40万，可向商务提交提额申请；
3.‘季度剩余可开票金额’=季度可开票金额-季度已开票金额-季度已结算未开票金额；季度开票限额为≤45万，可向商务提交限额申请；
4.‘自然年剩余可开票金额’=自然年可开票金额-自然年已开票金额-自然年已结算未开票金额；自然年指当年1月1日-12月月31日；自然年开票限额为≤180万，可向商务提交提额申请；
5.‘连续12个月剩余可开票金额’=连续12个月可开票金额-连续12个月已开票金额-连续12个月已结算未开票金额；连续12个月指查询时间月（含）往前推11个月（含）计算；连续12个月可开票限额为≤495万。
6.‘剩余可开票金额’指季度剩余可开票金额与自然年剩余可开票金额与连续12个月剩余可开票金额比对，取最小限额。查询所得的剩余可开票金额为当前时间内个体户可开票金额。
注：由于提交的结算金额为个体户收入的税前金额或税后金额的差异，固开票金额不一定等于结算金额。一般情况在税后模式下结算金额小于开票金额，税前模式下结算金额=开票金额。