2.结算接口
# 结算要求限制
◆ 每笔金额上限为 ==**5w**== 元，超过5w超出风控范围，将会直接返回失败，不可继续走确认结算。
◆ 银行卡，姓名，身份证不符，直接返回失败，三要素不匹配。
◆ 每个人每个月不得超过 ==**9.96w**== 元，超出则直接返回结算失败。
◆ 测试环境结算mock：单笔结算金额 ==**个位数**== 为 **++奇数（1、3、5、7、9）则成功++**，**++偶数（0、2、4、6、8）则失败++**。例子：成功（11、 11.02） 失败（12、 12.01）。
>d 平台根据实际业务，分为以下两种结算方式，可根据贵司实际业务场景选择一种合适的结算方式
方式一：提交订单、确认结算，分两个步骤完成。
方式二：提交确认结算，一个操作直接完成结算。
## 1.结算
### 1.1 提交订单接口
>d 备注：该接口所生成订单超过五天未确认结算，系统会默认清除
#### 接口地址：
/open/api/v1/bill/submitBill
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|thirdOrderId|商户订单号|String(32)|是|商户自己生成，具有唯一性|
|thirdBizOrderId|第三方业务订单ID|String(32)|否|该参数为商户自己的业务订单号，通过该订单号能够查询该笔金额来源明细|
|batchNo|批次号|String(32)|否|由第三方自己控制哪些订单为同一个批次号，开票的时候可根据批次号开票|
|payeeName|收款人姓名|String(32)|是||
|payeeIdCard|收款人身份证号码|String(18)|是||
|payType|支付类型|Integer(2)|是|支付类型该参数值填写支付类型对应数字即可 0:银行卡 1:支付宝 2:微信|
|payeeAccount|收款账户|String(128)|是||
|amount |收款金额|BigDecimal(10,2)|是|精度：小数点后两位|
|wxAppId|微信appId|String(64)|否|特殊情况需传入此参数|
|payeePhone|收款人手机号|String(16)|否|该参数用于用户接收到款短信|
|payeeBankName|收款账户开户银行|String(128)|否||
|payeeBankNo|收款账户开户银行联行号|String(30)|否||
|transName|转账备注|String(20)|否|备注字数不可超过20个字符|
|callBackUrl|自定义回调地址|String(512)|否|该参数应用于该笔订单指定的回调地址，若传了该地址，则该笔订单的结果会通知至该地址。|
|taskNo|关联服务编码|String(32)|否|由商户自行评估该提交结算订单是否需要关联服务|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billId| SSC平台订单号| Long|是|用于确认结算接口的入参|
|thirdOrderNo| 商户提交时的订单号|String| 是||
|transNo|交易号|String| 是|平台交易明细单号|
|checkStatus| 检测状态 |Integer|是|-1：检测失败 1：检测成功|
|reason| 失败原因|String| 是||
### 1.2 确认结算接口
#### 接口地址：
/open/api/v1/bill/sureGrant
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|billId|订单ID|Long(11)|是|该值由提交订单接口返回|
|mainstayId|主体ID|Integer(2)|是|该参数由 [查询商户可开票列表，以及所拥有的主体接口](doc:YdC9DUA9) 可获的|
|invoiceCode|发票编号|String(32)|是|该参数由 [查询商户可开票列表，以及所拥有的主体接口](doc:YdC9DUA9) 可获的|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 第三方订单号|String| 是|生成订单接口的thirdOrderId字段的值|
|transNo|交易单号|String|是|平台交易明细单号|
|status| 结算结果状态|String| 是|详情请参考[结算结果状态码](https://easydoc.net/docs/jg3t6THA/95180784/Ry461Ra3/g5SDIGDl)|
|returnMsg| 返回信息|String|是| ||
## 2.提交确认结算接口
时序图：
流程图：
#### 接口地址：
/open/api/v1/bill/payment
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义| 数据类型|是否必填|参数备注|
|-|-|-|-|-|
|thirdOrderId|商户订单号|String(32)|是|商户自己生成，不可重复提交|
|thirdBizOrderId|第三方业务订单ID|String(32)|否|该参数为商户自己的业务订单号，通过该订单号能够查询该笔金额来源明细|
|payeeName|收款人姓名|String(32)|是||
|payeeIdCard|收款人身份证号码|String(18)|是||
|payType|支付类型|Integer(2)|是|支付类型该参数值填写支付类型对应数字即可 0:银行卡 1:支付宝 2：微信|
|payeeAccount|收款账户|String(128)|是||
|amount |收款金额|BigDecimal(10,2)|是|精度：小数点后两位|
|wxAppId|微信APPID|String(64)|否|特殊情况需传入此参数|
|payeePhone|收款人手机号|String(16)|否|该参数用于用户接收到款短信|
|payeeBankName|收款账户开户银行|String(128)|否||
|payeeBankNo|收款账户开户银行联行号|String(30)|否||
|transName|转账备注|String(20)|否||
|callBackUrl|自定义回调地址|String(512)|否|该参数应用于该笔订单指定的回调地址，若传了该地址，则该笔订单的结果会通知至该地址。|
|mainstayId|主体ID|Integer(2)|是|该参数由 [查询商户可开票列表，以及所拥有的主体接口](doc:YdC9DUA9) 可获得|
|invoiceCode|发票编码|String(64)|是|该参数由 [查询商户可开票列表，以及所拥有的主体接口](doc:YdC9DUA9) 可获得|
|remark|拓展字段|String(255)|否|商户备注字段|
|extStatus|拓展状态|String(32)|否|特殊意义字段 restrictPay：限制支付。可根据不同对方双方协定自定义该字段值|
|extNeedCallBack|检测失败是否需要回调|String(2)|是|默认不回调，需要回调则传入参数：1|
|taskNo|关联服务编码|String(32)|否|由商户自行评估该提交结算订单是否需要关联服务|
#### 接口响应参数data字段解密后的参数说明：
>d 回调参数解密请参考 [回调说明](https://easydoc.net/doc/95180784/Ry461Ra3/IVn3pmlF#nav_7)
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 商户提交时的订单号|String| 是||
|transNo|交易号|String| 是||
|checkStatus| 检测状态 |Integer|是|-1：检测失败 1：检测成功|
|reason| 失败原因|String| 是||
|remark|拓展字段|String|否|商户备注字段|
#### 接口响应失败code说明：
>d 接口相应失败的时候可根据具体code码进行处理
|errorCode| errorMessage| 备注说明|
|-|-|-|
|NOT_CREATE_TASK| 主体和开票内容对应的任务未创建或者未审核通过，请确认后发放|先跟平台方沟通确认后后再原订单重试|
|DATA_NOT_EXIST| 商户配置不存在|先跟平台方沟通确认后后再原订单重试|
|BILL_CAN_NOT_DO| 您没有权限申请发放|先跟平台方沟通确认后后再原订单重试|
|ORDERNO_REPEAT| 请勿重复提交|不可以直接置为失败，需要主动查询,在根据返回值进行更新订单状态,避免第一次成功了后续重复提交返回了该错误又将订单置为失败的情况|
|MAINSTAYID_NOT_EXIST| 主体信息不存在|属于参数不符合-订单未入库，可修改后原订单号重试|
|MAINSTAY_UNUSED| 该主体已冻结|先跟平台方沟通确认后后再原订单重试|
|NOT_INVOICE| 您暂无该发票|先跟平台方沟通确认后后再原订单重试|
|PAY_TIME_LIMIT| 非常抱歉，由于***系统升级中，暂时无法使用***进行结算，建议您优先使用其他方式进行处理|先跟平台放沟通后在可结算的时间点内再进行原订单重试|
|BILL_INSUFFICIENT_BALANCE| 余额不足,请充值|充值后，可原订单提交|
|BILL_SAVE_ERROR| 订单保存失败，请稍后再试|先进行查询，如订单不存在在进行重试|
|BILL_DO_PAYING| 该笔订单正在发放，请稍后再试|该笔订单已经是结算中的状态,可等回调接口或者主动查询结果接口即可|
|UNABLE_TO_SETTLEMENT|暂不能结算，请联系客服|暂不能结算，请联系客服|
## 3.结算结果异步回调
>d 回调参数解密请参考 [回调说明](https://easydoc.net/doc/95180784/Ry461Ra3/IVn3pmlF#nav_7)
#### 请求方式：POST
解密结果示例如下：
```json
{
"callbackType": "payResult",
"itemStatus": "2",
"amount": "12.01",
"transNo": "xxxxx",
"thirdOrderNo": "xxxxx",
"paymentTime": "2019-07-05 23:41:45",
"reason": "",
"errorCode": "",
"remark": "",
"realPaymentAmount": "0.01",
"cooperateExpensesAmount": "0.01",
"cooperateExpensesTax": "0.001"
}
```
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|callbackType|回调类型|String|是|固定返回：payResult|
|itemStatus| 订单状态|String| 是|2:结算成功 -1:结算失败 |
|amount| 结算的金额|String| 是|实际结算的金额|
|transNo|平台订单号|String|是||
|thirdOrderNo| 结算订单号|String| 是||
|paymentTime| 结算时间|String| 是||
|reason| 失败原因|String| 是||
|errorCode| 失败编码|String| 是|失败时返回|
|remark|拓展字段|String|否|商户备注字段|
|realPaymentAmount|总支付金额|String|否|后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额（到账金额）+合作费用|
|cooperateExpensesAmount|合作费用|String|否|后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额*合作费率|
|cooperateExpensesTax|合作费率|String|否|后置收费模式有值。查询商户是否为后置收费可联系商务。|
## 4.结算结果查询接口
#### 接口地址：
/open/api/v1/bill/queryResult
#### 请求方式：POST
#### 请求参数说明：
>d 该接口参数无需参数名称只需将商户订单号拼接处json数组即可
示例：String data = [\"orderNo1\",\"orderNo2\"... ,\"orderNo10\"];
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|无参数名称|需要查询的商户订单号|是|最多查询10条记录|
未加密请求参数示例如下：
```json
[
"order11111",
"order22222"
]
```
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 商户订单号|String| 是||
|transNo|平台订单号|String|是||
|itemStatus| 订单状态|Integer| 是|详情请参考[结算结果状态码](https://easydoc.net/docs/jg3t6THA/95180784/Ry461Ra3/g5SDIGDl)|
|amount| 结算的金额|String| 是|实际结算的金额|
|paymentTime| 结算时间|String| 否|结算成功返回|
|reason| 失败原因|String| 是||
|errorCode| 失败编码|String| 是|失败时返回|
|remark|拓展字段|String|否|商户备注字段|
|realPaymentAmount|总支付金额|String|否|后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额（到账金额）+合作费用|
|cooperateExpensesAmount|合作费用|String|否|后置收费模式有值。查询商户是否为后置收费可联系商务。计算方式：提交金额*合作费率|
|cooperateExpensesTax|合作费率|String|否|后置收费模式有值。查询商户是否为后置收费可联系商务。|
解密结果示例如下：
```json
[
{
"transNo": "xxxxx",
"itemStatus": 2,
"amount": "12.01",
"thirdOrderNo": "xxxxx",
"paymentTime": "2019-07-05 23:41:45",
"reason": "",
"errorCode": "",
"remark": "",
"realPaymentAmount": "0.01",
"cooperateExpensesAmount": "0.01",
"cooperateExpensesTax": "0.001"
},
...
]
```
## 5.电子回单
### 5.1.获取电子回单接口
#### 接口地址：
/open/api/v1/bill/queryVoucherUrl
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|thirdOrderId|第三方订单ID|String|是||
|callbackUrl|回调地址|String|否|如果电子回单未生成，将会记录回调地址，等电子回单生成后主动推送，调用此地址，重复提交（相同订单号）视为修改回调地址（入参空地址则不修改），一个订单只会回调一次|
#### 接口响应参数data字段解密后的参数说明：
>d 该接口解密后的data字段即为电子回单的url
结果示例
“https://xxxxxx”
如果 data字段为空则代表未取得回单
### 5.2.电子回单回调接口
>d 回调参数解密请参考 [回调说明](https://easydoc.net/doc/95180784/Ry461Ra3/IVn3pmlF#nav_7)
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|thirdOrderNo|商户订单号|String|是||
|status|电子回单状态|Integer|是|固定传1-制作完成；|
|voucherUrl|电子回单下载地址|String|是||
## 6.取消订单接口
#### 接口地址：
/open/api/v1/bill/cancel
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|billId|平台返回的订单ID|Long(11)|是||
|reason|取消原因|String(30)|否||
#### 接口响应参数data字段解密后的参数说明：
>d 该接口响应参数中无响应data字段 ,success 等于true代表取消成功，false 代表失败 errorMessage中有错误信息反馈
## 7.获取对账单接口
### ~~7.1.获取对账单文件接口~~（不再维护）
>d 最新接口前往 [查看](https://easydoc.net/docs/jg3t6THA/34949871/grcmeR1I/mnWkEMuT#nav_6)
#### 接口地址：
/open/api/v1/bill/companyReconciliation
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|date|需要对账的日期|是|该参数为String类型 yyyy-MM-dd,例如 “2019-07-20”。|
示例：
```java
String paramsJson= "{\"date\":\"2019-07-20\"}";
String data = RSAHelper.encryptByPublicKey(paramsJson, publicKey);
```
>d 备注：系统每天9.30点生成前一天的对账单。建议每天10点后拉取对前一天的对账单
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 是否必有| 参数备注|
|-|-|-|-|
|fileUrl|对账文件URL|是|查询的某一天的对账单文件链接，通过该链接可下载对账单内容(该链接有效期为30分钟，30分钟后获取则需要重新调用接口生成新的链接)|
解密结果示例
`{"fileUrl":"https://qiniu.lx-rhino.com/3c59dc048e8850243be8079a5c74d079/2019-07-20.csv"}`
### 7.2.对账单数据分页获取接口
#### 接口地址：
/open/api/v1/bill/companyReconciliationList
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|pageNo|数据页数|Integer|是||
|pageSize|数据条数|Integer|是|最大限制100条|
|date|对账日期|String|是|格式yyyyMMdd，例如：20220303|
|ifFull|是否是全量对账单|Integer|是|0-（非全量）成功结算账单 1-全量账单|
#### 接口响应参数data字段解密后的参数说明：
|参数名称|参数含义|数据类型|是否必有|参数备注|
|-|-|-|-|-|
|current|当前页|Integer|是|当前页码|
|total|数据总条数|Integer|是|数据总条数|
|records|数据列表|list|是|数据列表，存的对象，下面的字段为对象里的属性|
|thirdOrderNo|商户订单号|String|是|生成订单接口的thirdOrderId字段的值|
|transNo|银行支付流水|String|是|银行支付流水|
|amount|收款金额|BigDecimal|是|提交结算金额|
|payeeAccount|收款人账户|String|是|收款人账户|
|payeeName|收款人姓名|String|是|收款人姓名|
|synchronizationTime|订单同步时间|String|是|订单结算时间|
|payType|支付类型|Integer|是|0:银行卡账户 1:支付宝账户 2:微信账户|
|itemStatus|订单状态|Integer|是|2:结算成功 -1:结算失败 -4:格式检查失败 |
|failReason|失败原因|String|否|失败原因|
#### 返回报文示例：
```java
{
'current': 1,
'hitCount': False,
'orders': [],
'pages': 1,
'records': [{
'amount': 50000.0,
'transNo': '12354...',
'failReason': '',
'itemStatus': '2',
'payType': '0',
'payeeAccount': '63431...',
'payeeName': '张三',
'synchronizationTime': '2021-11-05 14:20:12',
'thirdOrderNo': '123123...'
},
...
],
'searchCount': True,
'size': 10,
'total': 10
}
```
## 8.查询用户每月可结算金额数
#### 接口地址：
/open/api/v1/available/credit
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCards|需要查询的身份证号码集合|List<String>(10)|是|最大长度查询10条记录,例如：[身份证1,身份证2,身份证3]|
|mainstayId|主体ID|Integer(2)|是||
eg:
```json
{
"idCards": ["xxxx", "xxxx"],
"mainstayId": 1
}
```
#### 响应参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|-|
|idCard| 身份证号|Srting| 是||
|availableAmount| 可结算金额|BigDecimal| 是||
## 9.纳税清单
### 9.1.纳税清单查询接口
#### 接口地址：
/open/api/v1/taxlist/query
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义| 数据类型|是否必填|参数备注|
|-|-|-|-|-|
|month|月份|String(32)|是|格式"yyyy-MM-dd" 例如："2021-11-26"|
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|companyName| 商户名称|String| 是||
|fileUrl|纳税清单文档|String| 否|多个用逗号隔开例如 https://xxxx.xxx.xx/1.pdf,https//xxxx.xxx.xx/2.pdf。如果该内容为空则说明还未获取到纳税清单文件|
|month| 年月|String| 是|格式"yyyy-MM-dd" 例如 2021-11-26|
### 9.2.纳税清单回调接口
>d 回调参数解密请参考 [回调说明](https://easydoc.net/doc/95180784/Ry461Ra3/IVn3pmlF#nav_7)
#### 请求方式：POST
#### 传给回调接口参数data 解密结果json说明：
解密结果示例如下：
```json
{
"companyName": "xxx有限公司",
"fileUrl": "https://xxx.xx.xx/1.pdf",
"month": "2021-11-26"
}
```
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|companyName| 商户名称|String| 是||
|fileUrl|纳税清单文档|String| 否|多个用逗号隔开例如 https://xxxx.xxx.xx/1.pdf,https//xxxx.xxx.xx/2.pdf。如果该内容为空则说明还未获取到纳税清单文件|
|month| 年月|String| 是|格式"yyyy-MM-dd" 例如 2021-11-26|