# 营收系统缴费接口文档

**版本：** 1.5  
**作者：** 曹红强  
**最后更新：** 2023/03/10

## 修订记录

| 版本号 | 修改日期 | 修改人 | 修改内容 |
|--------|----------|--------|----------|
| v1.0 | 2021/03/24 | 曹红强 | 初始版本 |
| v1.1 | 2021/04/04 | 曹红强 | 新增代扣相关接口 |
| v1.2 | 2021/12/21 | 曹红强 | 完善文档结构及说明 |
| v1.3 | 2022/01/25 | 晋腾飞 | 完善文档结构及说明 |
| v1.4 | 2022/05/02 | 晋腾飞 | 添加托收相关接口 |
| v1.5 | 2023/03/10 | 晋腾飞 | 添加加密方式说明 |

## 概述

本文档主要是针对营收系统和银行（或代收机构）间的实时收费、银行代扣、银行托收（小额支付）协议。

## 术语

1. **商户/第三方支付平台/支付平台/第三方/支付公司**：指第三方支付公司（比如支付宝、微信等）或者银行（比如招商银行、平安银行等）。
2. **公用事业单位**：指接入的缴费事业单位，例如自来水公司、电力公司等。第三方支付发起的实时交易经总行和分行转发最终到公用事业单位进行处理。

## 通讯模式

- **通讯协议**：HTTP
- **提交方式**：POST
- **加密方式**：在请求头Header中填写
- **参数格式**：HTTP包体中采用XML或JSON格式，默认XML格式
- **服务端口和地址**：由公用事业单位提供
- **超时时间**：银行方接收接口返回超时时间建议设置为30秒

## 报文说明

### 报文格式

#### XML格式示例

```xml
<?xml version="1.0" encoding="GBK"?>
<in>
    <Version>1.0.1</Version>
    <InstId>缴费渠道</InstId>
    <TranCode>交易码</TranCode>
    <TranDate>交易日期</TranDate>
    <TranSeq>交易流水号</TranSeq>
    <TAG1>VALUE1</TAG1>
    <TAG2>VALUE2</TAG2>
</in>
```

#### 报文说明

1. **编码方式**：报文中固定写"GBK"，实际编码采用GBK
2. **in**：根节点
3. **Version**：固定写"1.0.1"
4. **InstId**：缴费渠道，最大长度5个字节，区别不同缴费渠道
5. **TranCode**：交易码
   - 账单查询：Query/QueryRes
   - 账单缴费：Pay/PayRes
6. **TranDate**：交易日期，格式YYYYMMDD
7. **TranSeq**：交易流水号，由银行系统产生，最大长度40个字节，同一天内不可重复

### 报文加密

#### 加密方式说明

加密方式填写在HTTP请求头Header里面，支持的加密方式：3DES、SM2、SM4

| 字段 | Header字段名 | 长度 | 约束条件 | 说明 |
|------|-------------|------|----------|------|
| 加密类型 | EncryptType | char(20) | 必填 | 3DES,SM2,SM4 (默认3DES) |
| 加密模式 | EncryptMode | char(20) | 必填 | 3DES(ECB), SM2(C1C2C3,C1C3C2), SM4(ECB,CBC) |
| 数据格式 | DataType | char(20) | 必填 | XML或JSON，默认XML |

#### 默认加密方式

如果HTTP请求头Header（EncryptType）不填写加密方式，默认为XML报文整体采用3DES函数加密，ECB模式PKCS7填充。加密后的报文用base64编码。

#### SM2加密方式

HTTP请求头Header字段EncryptType填写SM2，默认加密模式为C1C3C2，默认报文body数据格式为XML。

#### SM4加密方式

HTTP请求头Header字段EncryptType填写SM4，默认加密模式为ECB，默认报文body数据格式为XML。

## 报文头

所有接口报文开始都有以下5个固定域：

| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 |
|----------|--------|------|----------|------|
| 版本号 | Version | char(20) | 必填 | 固定为1.0.1 |
| 缴费渠道 | InstId | char(5) | 必填 | 由水司软件方提供 |
| 交易码 | TranCode | char(20) | 必填 | 见交易码说明 |
| 交易日期 | TranDate | char(8) | 必填 | YYYYMMDD |
| 流水号 | TranSeq | char(40) | 必填 | 银行系统产生的唯一流水号 |

### 交易码说明

- 账单查询：Query/QueryRes
- 账单缴费：Pay/PayRes
- 代扣签约：Signing/SigningRes
- 代扣解约：Termination/TerminationRes
- 代扣送盘：SendDisc/SendDiscRes
- 代扣回盘：BackDisc/BackDiscRes
- 取消代扣：CancelDisc/CancelDiscRes

## 接口规范

### 1. 账单查询接口

#### 请求接口
- **接口地址**：`/api/app/billQuery/query`
- **请求方法**：POST
- **交易码**：Query

#### 请求参数

| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 |
|----------|--------|------|----------|------|
| 客户编号 | billKey | char(35) | 必填 | 用水户的唯一标识 |
| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 |
| 开始条数 | beginNum | Num(5) | 可选 | 默认1 |
| 查询条数 | queryNum | Num(5) | 可选 | 默认1，最大100 |
| 扩展字段1 | filed1 | char(100) | 可选 | 扩展字段 |
| 扩展字段2 | filed2 | char(100) | 可选 | 扩展字段 |
| 扩展字段3 | filed3 | char(100) | 可选 | 扩展字段 |
| 扩展字段4 | filed4 | char(100) | 可选 | 扩展字段 |

#### 请求示例

```xml
<?xml version="1.0" encoding="GBK"?>
<in>
    <Version>1.0.1</Version>
    <InstId>00001</InstId>
    <TranCode>Query</TranCode>
    <TranDate>20180101</TranDate>
    <TranSeq>123456789012</TranSeq>
    <billKey>123456</billKey>
    <companyId>654321</companyId>
    <beginNum>1</beginNum>
    <queryNum>1</queryNum>
    <filed1></filed1>
    <filed2></filed2>
    <filed3></filed3>
    <filed4></filed4>
</in>
```

#### 应答参数

| 中文域名 | 标签名 | 长度 | 说明 |
|----------|--------|------|------|
| 返回代码 | RespCode | char(7) | 查询返回代码 |
| 返回说明 | RespMessage | char(60) | 查询返回说明 |
| 客户编号 | billKey | char(35) | 原样返回 |
| 机构编码 | companyId | char(30) | 原样返回 |
| 总条数 | totalNum | Num(5) | 查询结果总条数 |

#### Data数据结构

| 中文域名 | 标签名 | 长度 | 说明 |
|----------|--------|------|------|
| 合同号 | contractNo | char(30) | 合同号码 |
| 客户姓名 | customerName | char(150) | 客户姓名 |
| 余额 | balance | Number(16,2) | 账户余额 |
| 缴费金额 | payAmount | Number(16,2) | 应缴费金额 |
| 开始日期 | beginDate | char(8) | 账单开始日期 |
| 结束日期 | endDate | char(8) | 账单结束日期 |

#### 应答示例

```xml
<?xml version="1.0" encoding="GBK"?>
<out>
    <Version>1.0.1</Version>
    <InstId>00001</InstId>
    <TranCode>QueryRes</TranCode>
    <TranDate>20180101</TranDate>
    <TranSeq>123456789012</TranSeq>
    <RespCode>AAAAAAA</RespCode>
    <RespMessage>查询成功</RespMessage>
    <billKey>123456</billKey>
    <companyId>654321</companyId>
    <totalNum>1</totalNum>
    <Data>
        <contractNo>123456</contractNo>
        <customerName>张三</customerName>
        <balance></balance>
        <payAmount>2314</payAmount>
        <beginDate></beginDate>
        <endDate></endDate>
    </Data>
</out>
```

### 2. 缴费接口

#### 请求接口
- **接口地址**：`/api/app/billPay/pay`
- **请求方法**：POST
- **交易码**：Pay

#### 请求参数

| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 |
|----------|--------|------|----------|------|
| 客户编号 | billKey | char(35) | 必填 | 用水户的唯一标识 |
| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 |
| 缴费日期 | payDate | char(14) | 必填 | YYYYMMDDHHMMSS |
| 客户姓名 | customerName | char(150) | 必填 | 客户姓名 |
| 缴费金额 | payAmount | Number(16,2) | 必填 | 缴费金额 |
| 合同号 | contractNo | char(30) | 必填 | 合同号码 |
| 查询类型 | queryType | char(1) | 可选 | 默认0，客户编号查询；1：条形码查询 |
| 二级渠道 | subChannel | char(1) | 可选 | 1:支付宝 2:微信 6:其它 |

#### 请求示例

```xml
<?xml version="1.0" encoding="GBK"?>
<in>
    <Version>1.0.1</Version>
    <InstId>00001</InstId>
    <TranCode>Pay</TranCode>
    <TranDate>20180101</TranDate>
    <TranSeq>123456789012</TranSeq>
    <billKey>123456</billKey>
    <companyId>654321</companyId>
    <payDate>20110513081540</payDate>
    <customerName>张三</customerName>
    <payAmount>5555</payAmount>
    <contractNo>123456</contractNo>
</in>
```

#### 应答参数

| 中文域名 | 标签名 | 长度 | 说明 |
|----------|--------|------|------|
| 返回代码 | RespCode | char(7) | 缴费返回代码 |
| 返回说明 | RespMessage | char(60) | 缴费返回说明 |
| 客户编号 | billKey | char(35) | 原样返回 |
| 机构编码 | companyId | char(30) | 原样返回 |
| 交易日期 | payDate | char(14) | 原样返回 |
| 缴费金额 | payAmount | Number(16,2) | 原样返回 |

#### 应答示例

```xml
<?xml version="1.0" encoding="GBK"?>
<out>
    <Version>1.0.1</Version>
    <InstId>00001</InstId>
    <TranCode>PayRes</TranCode>
    <TranDate>20180101</TranDate>
    <TranSeq>123456789012</TranSeq>
    <RespCode>AAAAAAA</RespCode>
    <RespMessage>缴费成功</RespMessage>
    <billKey>123456</billKey>
    <companyId>654321</companyId>
    <payDate>20110513081540</payDate>
    <payAmount>5555</payAmount>
</out>
```

### 3. 账单红冲接口

#### 请求接口
- **接口地址**：`/api/app/payInvalid/payInvalid`
- **请求方法**：POST
- **交易码**：PayInvalid

#### 请求参数

| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 |
|----------|--------|------|----------|------|
| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 |
| 交易日期 | payDate | char(14) | 必填 | YYYYMMDDHHMMSS |
| 红冲流水号 | agencyBillNo | char(30) | 必填 | 缴费时的账单流水号 |
| 缴费金额 | payMoney | char(30) | 必填 | 缴费金额 |

**说明**：只可红冲当天收费且未对账交易，红冲成功后银行需发起自动退款。

### 4. 代扣签约接口

#### 请求接口
- **接口地址**：`/api/app/bankWithholding/signing`
- **请求方法**：POST
- **交易码**：Signing

#### 请求参数

| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 |
|----------|--------|------|----------|------|
| 客户编号 | billKey | char(35) | 必填 | 用水户的唯一标识 |
| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 |
| 签约日期 | signingDate | char(8) | 必填 | YYYYMMDD |
| 开户名 | accountName | char(150) | 必填 | 开户名 |
| 开户账号 | accountNo | char(30) | 必填 | 用户的账号 |
| 银行名称 | bankName | char(150) | 可选 | 总行名称 |
| 合同号 | contractNo | char(150) | 可选 | 合同号 |
| 协议号 | agreementNo | char(150) | 可选 | 协议号 |
| 银行类型 | bankType | char(1) | 可选 | 0：本行 1：他行 |

### 5. 代扣解约接口

#### 请求接口
- **接口地址**：`/api/app/bankWithholding/termination`
- **请求方法**：POST
- **交易码**：Termination

### 6. 代扣送盘接口

#### 请求接口
- **接口地址**：`/api/app/bankWithholding/sendDisc`
- **请求方法**：POST
- **交易码**：SendDisc

### 7. 代扣回盘接口

#### 请求接口
- **接口地址**：`/api/app/bankWithholding/backDisc`
- **请求方法**：POST
- **交易码**：BackDisc

## 对账文件

### 对账文件格式

对账文件为文本文件txt格式，编码格式为UTF-8，包括明细行和汇总行。行内每个分项之间以"|"为分隔符。

#### 汇总行格式
```
交易笔数|总金额
```

#### 明细行格式
```
交易日期|交易流水号|客户编号|缴费金额|二级渠道|交易类型
```

#### 文件命名规则
```
机构编码(companyId)_对账日期.txt
```

其中对账日期为交易当天日期非当前时间。

## 返回代码说明

| 序号 | 错误码 | 错误说明 |
|------|--------|----------|
| 0 | AAAAAAA | 成功 |
| 1 | DEF0001 | 无相应记录 |
| 2 | DEF0002 | 用户未欠费 |
| 3 | DEF0003 | 与第三方通讯失败 |
| 4 | DEF0004 | 超过受理期,银行不予受理,请至缴费单位缴费 |

## 附录

### 扣款结果标志说明

- **0**：扣款成功，其余状态按失败处理
- **1**：扣款失败，余额不足
- **2**：账号、户名错误
- **3**：账号不存在
- **4**：重复扣款
- **99**：其他原因

### 二级渠道说明

- **1**：支付宝
- **2**：微信
- **6**：其它

### 银行类型说明

- **0**：本行
- **1**：他行