工行银企互联开发手册

1、第1章概述银企互联面向大的集团客户，提供与企业ERP系统直连的平台，银企互联面向大的集团客户，提供与企业ERP系统直连的平台，为工行的现金管理服务提供多渠道和客户化支 持。企业ERP系统通过HTTPS协议与工行系统进行连接并向银企互联前置发送数据，数 据的接口格式使用标准的 xml数据格式，但双方通讯的过程中则需要遵守下文描述的规定。 银企互联前置接到企业数据后进行一系列的检查后完成交易，并将处理结果以企业便于处 理的形式返回给企业。在安全保证方面，通讯层的安全保证是HTTPS协议。企业如需使用银企互联系统，要办理有关注册手续，并审领证书。企业进行结算类交易时，如果涉及到授权过程，企业需要在企

2、业网银系统中完成相关 授权动作。银企互连系统将企业提交的支付指令或者授权成功后的指令当作最终转账指 令，根据提交指令的证书ID检查收付方帐号等合法性，以保证所提交指令在权限允许范围内进行操作。第2章总体方案介绍2.1总体网络结构图银企互联系统上图企业ERP系统1采用的是非NC方式接入的客户；企业 ERP系统2采用的是NC方式 接入的客户；2.2企业端安全服务器简介它有两个可以配置的端口分别用于加密和签名/验签服务，如下图所示（假设1为加密端口,2为签名/验签端口）。1. http父易请求包1 （加密）R2.交易结果NetSafehttps父易请求包1Client!r1.签名/验签请求2 （签名

3、/验签）2签名/验签结果具体使用时，企业应用向工行提交交易请求时，可以依照http协议向NetSafe Client的端口1发送请求。接到请求后，NetSafe Client使用企业证书将 http请求包转换成https请求包发往工行端服务器；如果需要对某些交易数据进行签名，则企业应用需要与签名端口建立Socket连接并将待签名数据发往端口 2,然后接收端口 2的签名结果，之后再将包含签 名信息的交易请求发往端口1而完成整个交易请求过程。对签名还是验签名请求的区分则是通过http包头来进行。Content-Type:INFOSEC_SIGN/1.0 和 Content-Type: INFOSE

4、C_VERIFY_SIGN/1.0分别用于标识签名请求和验签名请求，而 Content-Type: INFOSEC_SIGN_RESULT/1.0 和 Content-Type: INFOSEC_VERIFY_SIGN_RESULT/1.0分别用于标识签名和验签名的返回结果。为方便起见，可以将NetSafe Client的两个服务端口逻辑地称为两台服务器，NetSafeClient的加密服务器和签名服务器。2.3安全控制介绍对于NC方式接入的客户企业向工行提交的交易数据，必须通过企业方的NetSafe Client进行与工行服务器的连接，接口确定需要签名的数据也必须由NetSafe Clien

5、t的签名服务器签名后组成规定的数据包格式后，通过NetSafe Client提交工行，这样可以保证企业数据以及相关信息不被恶意篡改。数据全部由NetSafe Client负责转发，使NetSafe Client成为架设在企业现场的工行接入服务器。而企业与工行之间安全的连接，由NetSafe Client和工行安全代理服务器 NetSafe 保证；工行接收到企业提交过来的部分关键交易数据后，需要解密并验证企业的数字 签名，以防止第三方假冒企业的行为。对于非 NC 方式接入的客户企业向工行提交交易数据时的安全控制企业 ERP 与银企互连系统之间使用 HTTPS 协议通讯。 企业可以选择是否对交易数

6、据进行对称加密，目前系统支持的算法有 DES 与3DES。进行对称加密可以防止第三方截获交易的信息。而加密中需要用到的密 钥由企业与工行共同约定。 （加密功能暂不支持） 企业需要对其发送的指令数据进行数字签名，签名中使用的证书可以是企业证 书也可以是工行证书，其中签名使用的算法是 SHA1withRSA 。进行数字签名可 以防止第三方假冒企业的行为。工行向企业发送结果信息时的安全控制企业 ERP 与银企互连系统之间使用 HTTPS 协议通讯。 企业可选择是否对返回数据进行对称加密，方法与上文相同。 工行对部分关键交易返回信息进行数字签名。第 3 章 重点说明所有的交易请求包中"包序列

7、ID ”字段（PackagelD）由企业产生，产生规则为当前日期（北京时间， 格式为 yyyyMMdd ）7位序列号 （例如 200212230000001，为 2002 年 12月 23日发送的一个交易请求包的包序列ID ）。在一个企业代码下当日包序列 ID必须唯一。 工行处理完毕之后将该字段原值返回， 即所有的交易返回包中 “包序列 ID” 字段（ PackageID）。转帐交易请求包中"签名时间”字段（ SignTime），格式为yyyyMMddhhmmssSSS （例如 20021223092710568，表示 2002 年 12 月 23 日 9 点 27 分 10 秒 5

8、68 毫秒）。签名时 间应为北京时间。签名时间如果与交易请求到达工行服务器时的北京标准时间误差过 大（暂定为 15 分钟），交易将无法进行。此措施将可以有效地防止黑客采用重放攻击 进行干扰帐务活动的行为。同一笔交易如果因为网络不正常等因素需要重新提交时， 要修改转账交易请求包的“签名时间字段”并重新签名。所有请求包和返回包中备用字段的使用主要是出于对今后扩展的考虑，如果以后需要 增加企业上送的项目或者返回给企业的信息，不必再改变交易包格式。目前对企业请 求包来说这些备用字段的值可以送空；企业对银行返回包中的备用字段也不必作处理。请求包中的备用字段标签为ReqReserved* ”，返回包中的备

9、用字段标签为 “RepReserved*”（其中*为1、2、3或4,详见接口说明文档）。查询历史明细返回数据包中交易时间（ <Trans_time></Trans_time> ）数值如为空， 则说明该笔指令是银行的计息交易明细。支付查询指令接口, 方便企业对可疑、 有疑问 （如网络中断, 交易长时间没有返回等） 或处理完毕的转帐指令进行查询。 企业提交要查询的结算请求的包序列 ID ,工行返回 该笔转帐指令的基本信息和状态。本接口说明中所有涉及金额的字段都是以分为单位（不带小数点）。如 企业系统需要代理汇兑功能则企业应用需同步开发网点信息下载交易,以便为代理 汇兑交易中

10、收方为它行情况时提供工行网点名称。 否则,无需开发网点信息下载交易。 在网点信息下载功能中,由于下载数据过大且数据不会经常更新,所以此交易控制了 企业每日下载次数。目前暂定次数为每日 2 次。个 人联名卡签权指令只支持币种是人民币的账号/卡号。企业端传输数据时,指定 xml 编码方式为 GB2312。银企互联提交包中包含“ <SignTime> 签名时间（ yyyyMMddhhmmssSS）S</SignTime> ” 此标签的,说明该交易需要进行签名处理。企 业端的程序需要对银行返回的数据有可扩展性,以便适应今后业务的不断发展。银 企互连系统支持两种接入方式,客户可以

11、任何选择一种。第一种：使用第三方NC软件方式接入银企互连系统；第二种：使用非 NC 方式企业直接接入银企互连系统； 下面将区分两类客户分别对接入方式等相关信息进行说明。第4章银企互联一一NC方式接入客户4.1 企业端系统环境要求4.1.1软件环境对企业的 ERP 系统无要求；工行企业端证书服务器软件 NetSafe Client 需安装在一台 PC 机上。4.1.2网络环境企业财务系统通过局域网与工商银行提供的 NetSafe Client 连接；企业端的 NetSafe Client 可以通过专线或 INTERNET 与中国工商银行银企互连系统互 联。4.1.3企 业开发过程描述4.1.3.

12、1 企业提交交易请求数据过程企业提交的交易分为两大类：查询类和结算类（需要进行签名处理） 。1、 查询类：（ 1 ） 企业按照工行提供的 xml 包格式进行打包，在局域网内通过 http 协议 以 POST 方式将交易包发送到 NetSafe Client 的安全 http 协议服务器。 http 请求格式： action=”http:/ 客户端 NetSafe Client 的地址和加密端口 号 /servlet/ICBCCMPAPIReqServlet?userID= 证书 ID &PackageID= 包序 列 ID &SendTime= 请求时间 ”请求数据格式（pos

13、t方式）：Version=版本号（区分版本时间，暂定）&TransCode= 交易代码（区分交易类型，每个交易固定 ）&BankCode= 客户的归属单位 &GroupCIS= 客户的归属编码 &ID= 客户的证书 ID （无 证书客户可空 ）&PackageID= 客户的指令包序列号 （由客户 ERP 系统产 生，不可重复 ）&Cert= 客户的证书公钥信息（进行 BASE64 编码； NC 客户送空 ） &reqData= 客户的 xml 请求数据其中：包序列ID、证书ID应根据实际情况进行更改，请求时间为企 业发出该交

14、易请求包的当前系统时间。 post 方式最后不允许有回车等 其 他 乱 字 符 ， TransCode 交 易 名 称 应 与 xml 包 内 标 签 <TransCode></TransCode> 中 的 值 一 致 ， action中 的 证 书 ID 、PackageID 与请求数据格式中的证书 ID、 PackageI D 、 xml 包中的证书 ID、 PackageID 的值三者相一致。（ 2） NetSafe Client 将 xml 包加密后按照 https 协议，通过互联网 /专线发送 到银行端的 NetSafe Server。（本步由NetSafe

15、Client完成，企业无需处理);(3)NetSafe Server将交易请求送银企互连系统进行处理。2、结算类：(1)企业按照工行提供的xml包格式进行打包，在局域网内与 NetSafeClient的签名端口建立 Socket连接，通过此连接向签名端口发送http数据包。http 包头中需包含"Content-Length ”和"Content-Type”两个属性。其中“ Content-Length: ”后面是需要签名的二进制数据包的 长度，“ Content-Type: ”后面是需要签名的标记，为INFOSEC_SIGN/1.0 。(注意大小写)http请求格式：ac

16、tion="http:客户端NetSafe Client的地址和签名端口号”请求数据格式：结算类请求提交的xml包NetSafe Client对xml包进行签名后， 通过http协议将签名结果返回给企业系统。如签名成功<sign>标签与</sign>标签之间的部分为签名结果。NetSafe Client返回的签名包如下：<html><head><title> 签名结果 </title><result>0</result></head><body><sign&g

17、t; MHIXAYJKovcNAQcCo .0BILdSgw= </sign></body></html>(2)企业按照工行提供的xml包格式进行打包，在局域网内通过http协议以POST方式将交易包发送到NetSafe Client的安全http协议服务器。http请求格式：action="http:客户端NetSafe Client的地址和加密端口 号/servlet/ICBCCMPAPIReqServlet?userlD=证书 ID&PackagelD=包序 列ID &SendTime=请求时间”请求数据格式（post方式）:

18、Version=版本号（区分版本时间，暂定）&Tra nsCode=交易代码（区分交易类型，每个交易固定）&Ban kCode=客户的归属单位 &GroupCIS=客户的归属编码 &ID=客户的证书ID （无 证书客户可空）&PackageID=客户的指令包序列号 （由客户ERP系统产 生，不可重复）&Cert=客户的证书公钥信息（进行 BASE64编码；NC 客户送空）&reqData=客户的xml请求数据其中：包序列ID、证书ID应根据实际情况进行更改，请求时间为企 业发出该交易请求包的当前系统时间。post方式最后不允

19、许有回车等其他乱字符，TransCode 交易名称应与xml包内标签<TransCode></TransCode> 中的值一致，action 中 的证书 ID、 PackageID与请求数据格式中的证书 ID、PackageID、xml包中的证书 ID、PackageID的值三者相一致。（3）NetSafe Client将企业送来的签名包加密后按照https协议，通过互联网/专线发送到工行端的NetSafe Server，再发往工行网银进行处理。（本步由NetSafe Client完成，企业无需处理）。企业接收交易响应数据过程企业接收到数据包的格式 ：re

20、qData=交易返回包或errorCode=错误代码步骤：判断返回数据中是否是errorCode：（1）如果是：根据错误代码做相应处理，结束。错误代码的含义参见接口说明文档 中的附录。（2 ）如果否：企业接收到数据包的格式： reqData=交易结果包；企业根据先进行 BASE64解码， 签名返回包按照格式拆分出明文和密文，验签正确后对明文按工行提供的xml包格式进行解包。对于单笔提交类指令（即存在文件级返回包的指令），返回的xml包格式按照指令级返回包格式来处理，多笔则按照文件级返回包格式来处理。企业接收银行主动返回过程http请求格式：action= "http:/

21、客户ERP服务器的地址和端口号 ”请求数据格式（post方式）：Version=版本号（区分版本时间，暂定）&Tra nsCode=交易代码（区分交易类型，每个交易固定）&Ban kCode=客户的归属单位 &GroupCIS=客户的归属编码 &ID=客户的证书ID （无 证书客户可空）&PackagelD=客户的指令包序列号 （由客户ERP系统产 生，不可重复）&Cert=客户的证书公钥信息（进行 BASE64编码；NC 客户送空）&reqData=客户的xml请求数据reqData数据格式：如果需要签名，格式为：数字字符

22、串：长度10位，代表明文数据长度，不足10位左补0;明文：xml明文，长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；分隔符：ICBCCMP密文：明文经过签名后的数据并做BASE64编码；如果不需要签名，则直接送xml明文；以上数据经过拼接后，再进行BASE64编码（仅reqData项）、URLEncode 编码（全部参数项）得到最终的reqData数据。按照以上格式将请求数据发送到企业；此格式返回的数据是不经过NC的，是银行直接发给企业的ERP系统；如有使用，企业需要在内管注册或者修改集团信息时填入企业用于接收银行反馈的地址，标准格式是http:/ip:port;编解码方式查看

23、 第5章银企互联 非NC方式接入客户5.1 企业端系统环境要求5.1.1软件环境对企业的 ERP 系统无要求；5.1.2网络环境企业财务系统可以通过专线与中国工商银行银企互连系统互联。5.1.3企 业开发过程描述 企业提交交易请求数据过程（ 1 ） 企业按照工行提供的 xml 包格式进行打包，在局域网内通过 http 协议 以 POST 方式将交易包发送到 NetSafe Client 的安全 http 协议服务器。 http 请求格式： action=”http:/ 客户端 NetSafe Client 的地址和加密端口 号 /servlet/ICBCCMPAPI

24、ReqServlet?userID= 证书 ID &PackageID= 包序 列 ID &SendTime= 请求时间 ”请求数据格式（post方式）：Version=版本号（区分版本时间，暂定） &TransCode= 交易代码（区分交易类型，每个交易固定）&BankCode=客户的归属单位 &GroupCIS= 客户的归属编码 &ID= 客户的证书 ID （无 证书客户可空 ）&PackageID= 客户的指令包序列号 （由客户 ERP 系统产 生，不可重复 ）&Cert= 客户的证书公钥信息（进行 BASE6

25、4 编码； NC 客户送空 ） &reqData= 客户的 xml 请求数据其中：包序列ID、证书ID应根据实际情况进行更改，请求时间为企 业发出该交易请求包的当前系统时间。 post 方式最后不允许有回车等 其 他 乱 字 符 ， TransCode 交 易 名 称 应 与 xml 包 内 标 签 <TransCode></TransCode> 中 的 值 一 致 ， action 中 的 证 书 ID 、 PackageID 与请求数据格式中的证书 ID、 PackageI D 、 xml 包中的证书ID 、 PackageID 的值三者相一致。reqDat

26、a 数据格式：如果需要签名： 数字字符串：长度 10 位，代表明文数据长度，不足10 位左补 0；明文： xml 明文，长度可变，需要上面的数据指明，双字节字符（汉 字）算作 1 位长度；分隔符： ICBCCMP；密文：明文经过签名后的数据并做BASE64编码；如果不需要签名，则直接送 xml 明文；以上数据经过拼接后，再进行BASE64编码得到最终的reqData数据。按照以上格式将请求数据发送到工行； 企业接收交易响应数据过程企业接收到数据包的格式：reqData=交易返回包或errorCode=错误代码reqData=交易返回包结构：如果交易返回包进行了签名，则结构为：数字

27、字符串：长度 10 位，代表明文数据长度，不足 10位左补 0； 明文：长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；分隔符： ICBCCMP ；密文：明文经过签名后的数据； 如果交易返回包没有签名，则结构为：明文； 不论是否签名，交易返回包均进行了BASE64编码；步骤：判断返回数据中是否是"errorCode= ”打头：（1）如果是：根据错误代码做相应处理，结束。错误代码的含义参见接口说明文档中的附 录。（2）如果否：企业接收到数据包的格式：reqData=交易结果包企业根据先进行 BASE64 解码，签名返回包按照格式拆分出明文和密文，验签正确后 对明文按工行提

28、供的 xml 包格式进行解包。对于单笔提交类指令（即存在文件级返回 包的指令），返回的 xml 包格式按照指令级返回包格式来处理，多笔则按照文件级返 回包格式来处理。 企业接收银行主动返回过程http请求格式：action= "http:/客户ERP服务器的地址和端口号 请求数据格式（post方式）：Version=版本号（区分版本时间，暂定）&Tra nsCode=交易代码（区分交易类型，每个交易固定）&Ban kCode=客户的归属单位 &GroupCIS=客户的归属编码 &ID=客户的证书ID （无 证书客户可空）&a

29、mp;PackagelD=客户的指令包序列号 （由客户ERP系统产 生，不可重复）&Cert=客户的证书公钥信息（进行 BASE64编码；NC 客户送空）&reqData=客户的xml请求数据reqData数据格式：如果需要签名，格式为：数字字符串：长度10位，代表明文数据长度，不足10位左补0;明文：xml明文，长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；分隔符：ICBCCMP密文：明文经过签名后的数据并做BASE64编码；如果不需要签名，则直接送 xml明文；以上数据经过拼接后，再进行BASE64编码（仅reqData项）、URLEncode编码（全部参数

30、项）得到最终的 reqData数据。按照以上格式将请求数据发送到企业；此格式返回的数据是银行直接发给企业的ERP系统；如有使用，企业需要在内管注册或者修改集团信息时填入企业用于接收银行反馈的地址，标准格式是http:/ip:port;编解码方式查看 企业签名验签过程在银企互联中，对于指令体的签名与验签工作由纯java版工行签名验签接口完成的。本文档对在专业版银企互联中使用的接口作出描述。同时提供了一套纯java版的从企业发送指令到工行系统和从工行系统接收处理结果的例子程序。从企业发送指令到工行系统的例子中包括了两方面的内容：用企业的数据层私钥对数据进行签名，然后用工行的通讯层公钥

31、进行通讯认证；从工行系统接收处理结果的例子中包括了两方面的内容：用企业的通讯层私钥要求通讯认证，然后用工行的数据层公钥进行数据的验签。使用这种接入方式的客户只能使用磁盘证书；该磁盘证书需要拆分， 拆分为一对数据层证书，用于签名验签；一对通讯层证书，用于建立与银行的https连接。拆分方法见第 7章企业签名验签方法总体介绍接口包含 icbc.jar 、 InfosecCrypto_Java1_02_JDK14.jar 、 org.mortbay.jetty.jar 、 tools.jar 四 个文件，使用时需要把这四个文件放置到java 的 classpath 目录中。该接口建议的 JDK 版本

32、为 1.4.2。（不要使用 JDK1.5 版本或者比 1.4 更低版本）接口使用的详细说明Sign（对原始数据进行数字签名的函数）public static bytesign (byte src,int len,byteprivateKey,charkeyPass)Description用 rsa 算法对一段消息签名Parameters:privateKey -为口令保护的私钥src - 为待签名消息len - 为待签名消息的长度keyPass -为私钥保护口令Returns:如果成功返回签名结果 , 如果失败返回 nullThrows:NoSuchProviderException -NoS

33、uchAlgorithmException -InvalidKeyException -cert,SignatureException -verifySign（对数字签名进行验签的函数）public static intverifySign (byte src,int len,bytebytesign)Description 用rsa算法对一段签名进行验证Parameters:cert -为证书src -为被签名的消息len -为被签名消息的长度sign -为签名的结果Retur ns:如果成功返回0,如果其它则失败Throws:Sign atureExcepti on -NoSuchAlgo

34、rithmExceptio n -In validKeyExceptio n -附件说明1. ceshizhang.cer , ceshizhang.key是一套客户证书的公钥与私钥，保护口令是 12345678。2. Test.java 是一个演示各个接口使用方式的测试程序。3. APIforZHEJIANG.rar指导企业开发的例子程序；使用说明例子的使用说明。4. 附件如下签名验签接umwi.ap https服务器建立开发支持请参考上面附件中 APIforZHEJIANG .rarAPIforZHEJIANGicbcapiserver.java 开发。使用说 明文档介绍了开发方法。 Base64编解码方法参考建议使用sun提供的BASE64编解码方法实现。/* base64 解码* params:需要解码的数据* return解码后的数据*/public staticStri ng getstrFromBASE64(Stri ng s) if (s = null )return null ;sun. misc.BASE64Decoder d