tangweijie f8b75f7771 docs: import bank api archive and openapi tooling

2026-03-27 10:12:47 +08:00

12 KiB

Raw Permalink Blame History

营收系统缴费接口文档

版本： 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	晋腾飞	添加加密方式说明

概述

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

术语

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

通讯模式

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

报文说明

报文格式

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>

报文说明

编码方式：报文中固定写"GBK"，实际编码采用GBK
in：根节点
Version：固定写"1.0.1"
InstId：缴费渠道，最大长度5个字节，区别不同缴费渠道
TranCode：交易码
- 账单查询：Query/QueryRes
- 账单缴费：Pay/PayRes
TranDate：交易日期，格式YYYYMMDD
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 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 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 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 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：他行

12 KiB Raw Permalink Blame History Unescape Escape

营收系统缴费接口文档

修订记录

概述

术语

通讯模式

报文说明

报文格式

XML格式示例

报文说明

报文加密

加密方式说明

默认加密方式

SM2加密方式

SM4加密方式

报文头

交易码说明

接口规范

1. 账单查询接口

请求接口

请求参数

请求示例

应答参数

Data数据结构

应答示例

2. 缴费接口

请求接口

请求参数

请求示例

应答参数

应答示例

3. 账单红冲接口

请求接口

请求参数

4. 代扣签约接口

请求接口

请求参数

5. 代扣解约接口

请求接口

6. 代扣送盘接口

请求接口

7. 代扣回盘接口

请求接口

对账文件

对账文件格式

汇总行格式

明细行格式

文件命名规则

返回代码说明

附录

扣款结果标志说明

二级渠道说明

银行类型说明

12 KiB

Raw Permalink Blame History