工行网上银行系统B2B商户(新接口)手册

1、 中国工商银行网上银行系统中国工商银行网上银行系统 B2BB2B 支付（新接口）支付（新接口）中国工商银行软件开发中心中国工商银行软件开发中心Copyright Reserved2005 年年 8 月月商户手册 网上银行商户手册Copyright ICBC SDC 2005.8 - 1 -1.文档属性文档属性内容文档名称：网上银行系统 B2B 商户(新接口)手册文档版本号：1.3文档状态：正式稿文档编写完成日期2005-092.文档变更历史清单文档版本号变更日期修改人变更内容简述1.12005-12-20解志超之前通知消息编码方式是将整个 http 请求的 bodycontent进行了 URL

2、 编码，不符合http 协议的格式，不利于商户端的开发。根据商户的建议修改为：对请求中的每个字段的值单独进行 URL 编码，这样商户端可以更方便的取到各个字段的值。1.22006-06-06解志超修正了文档的一些错误1.32006-10-25解志超请求接口中增加收款人名称字段 网上银行商户手册Copyright ICBC SDC 2005.8 - 2 -前前 言言该文档包括客户通过商户网站的中国工商银行网上银行的中国工商银行网上银行的“B2B 网上支付网上支付”URL 超链进行 B2B 新接口网上支付时，商户必须向银行提供的部分订单信息及其格式；中国工商银行向商户返回客户付款情况信息的内容、格

3、式、验证签名程序的接口及调试用的例子。 网上银行商户手册Copyright ICBC SDC 2005.8 - 3 -目目 录录前 言.2目 录 .31商户端的接口商户端的接口 .41.1 参数名及其内容列表.41.2 商户请求中签名数据产生方法.51.3 一个链接例子.72银行反馈信息的接口银行反馈信息的接口 .82.1 通知消息接口数据格式：.82.2 通知消息的FORM格式： .102.3 通知消息处理过程.113.商户端系统环境要求商户端系统环境要求.133.1 软件环境.134.常见问题常见问题.13问题 1 返回一个空白页面，页面中只有五位错误代码.13问题 2 返回超时页面.14

4、 网上银行商户手册Copyright ICBC SDC 2005.8 - 4 -1商户端的接口商户端的接口客户通过商户的网站与卖方进行 b2b 网上定购交易，确认订单后通过商户网站提供的“中国工商银行网上支付”超链，进入中国工商银行的网上支付画面进行支付。为此商户网站必须将该订单中的部分信息以 Form 提交方式中的Post 方法，将数据提交到中国工商银行指定的的网上支付 URL (https:/*.*.*.*/servlet/ICBCINBSEBusinessServlet，严格区分大小写，严格区分大小写,请联系所在地分请联系所在地分行确认投产环境和测试环境的行确认投产环境和测试环境的 IP

5、 地址地址)中。1.1 参数名及其内容列表参数名及其内容列表变量名称变量名称变量命名变量命名长度定义长度定义说明说明接口名称APINameMAX (30)必输，签名，上送“B2B”，区别大小写！接口版本号APIVersion=15必输，签名,上送”001.001.001.001”商户代码Shop_code=14必输，签名，唯一确定一个商户的代码，商户在工行开户时，由工行告知商户支付结果信息通知程序地址MerchantURLMAX (200)必输，签名，使用 HS 接口模式的商户用来接收工行订单支付结果信息的程序名字和位置。订单号ContractNoMAX(30)必输，签名，客户支付后商户网站产

6、生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。订单金额ContractAmtMAX(18)必输，签名，客户支付订单的总金额，一笔订单一个，保留到分，无小数点，如金额为1.00 元，上传数据为“100”支付币种Account_cur= 3必输，签名，用来区分一笔支付的币种。目前工行只支持人民币（001）支付。定义如下：001 人民币检验联名标志JoinFlag必输，签名，固定上送 2订单签名数据Mer_Icbc20_signstr无限制必输，生成签名数据的方法见后面的说明商城证书数据Cert无限制必输，商户端读取本地商户证书文件后，

7、再使用工行提供的 API 进行 Base64 编码后产生的商户证书数据字串。结果发送类型SendType=10 -成功失败信息都发送1 - 只发送成功信息必输，签名，如果取 0，工行向商户发送一笔订单的每一次交易结果，无论支付成功或者失败，如果取 1，工行只向商户发送交易成功的通知信息。当在付款人一方 b2b 支付指令经过指令批复后提交的，结果发送类型默认为成功失败都发送，这时不取商户上送的发送类型。 网上银行商户手册Copyright ICBC SDC 2005.8 - 5 -交易日期时间TranTime=14必输，签名，YYYYMMDDHHmmss。与工行系统当前时间差为：前 1 小时，后

8、 12 小时商城账号Shop_acc_numMAX (19)必输，签名收款单位账号PayeeAcctMAX (19)必输，签名商品编号GoodsCodeMAX (30)选输商品名称GoodsNameMAX (60)选输订单数量AmountMAX (10)选输已含运费金额TransFeeMAX (18)选输商城提示ShopRemarkMAX (120)选输，最多 120 字符商城备注字段ShopRemMAX(100)选输，最多 100 字符收款人名称PayeeNameMAX(60)选输，最多 60 字符，30 个汉字注意注意：1. 从商户 Post 过来的数据，参数的名称必须与上表中完全相同，名

9、称中的字母大小写均要相同，不能进行随意更改(在 form 中的提交按钮中 submit 不能有 Name 属性)；此外，如果其他 input 项的 Name中使用了双引号，如：，则一定注意在引号内不要包含空格，不要写成“Merchant URL ”或者“ Mer chantURL” ，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付。2.接口名称和版本号一定要和上表中相同。3.为了保证中文信息的正确性，商户请求的数据字符集要求是 GBK。4.商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。5.商户证书对于商城账号必须有定购操作权限，收款账号可以和商

10、城账号不相同，上送的商城账号与收款人账号相同时，则后续可提供退货、返还操作。如果付款人有任意账号转账权限，那么收款账号可为任意的工行 19 位账号，否则收款账号必须为付款人所在集团在网银注册的可收款的 19 位账号，此接口不支持低于 19 位的老账号。6.关于新增的收款人名称字段：如果商户在这个字段上送了收款人名称那么客户在支付页面就不用输入了，会取上送的收款人名称；如果商户没有上送那么会在商户所在企业网银集团所有提交 id 的收款人名册（可以在企业网银的 付款业务-网上汇款-收款人名册 栏目中维护收款人名册）中查找是否有交易中的收款账号，如果有就会取收款 网上银行商户手册Copyright

11、ICBC SDC 2005.8 - 6 -人名册的收款人名称，这时也不用客户输入收款人名称；如果以上两种情况都不满足那么在支付页面就需要客户输入收款人名称。请商户根据自身情况选择收款人名称的获得方式。对于已经开发完成的商户不上送这个字段也可以继续使用接口，不会影响已有功能。1. 2 商户请求中签名数据产生方法商户请求中签名数据产生方法 签名信息字段签名信息字段 Mer_Icbc20_signstr 的产生的产生通过调用工行提供的签名 API，用商户自己的私钥对交易数据和商户信息数据进行数字签名，产生签名结果。步骤如下：1组织要签名的数据串（串的顺序不可改变）组织要签名的数据串（串的顺序不可改变

12、）数据串为：APIName=B2B&APIVersion=001.001.001.001&Shop_code=商户代码&MerchantURL =支付结果信息通知程序地址&ContractNo=订单号&ContractAmt=订单金额&Account_cur=001&JoinFlag=2&SendType=结果发送类型&TranTime=接收交易日期时间& Shop_acc_num =商城账号&PayeeAcct =收款单位账号注意：串中间不要有空格注意：串中间不要有空格2调用签名接口对数据签名，接口如下：

13、调用签名接口对数据签名，接口如下：C 接口接口int sign(char *src, int srcLen, unsigned char *privateKey, int keyLen, char *keyPass, unsigned char *signBuf, int *signBufLen)。参数说明：src 为要签名的数据，其长度为：srcLen;privateKey 为其私钥，长度为：keyLenkeyPass 为私钥密码signBuf 为保存签名的缓冲区的指针，空间由 API 内部分配。签名后将签名数据保存在此。指针空间的释放由应用程序负责。signBufLen 存放签名数据的长度

14、指针。返回：0 正确，其它错误JAVA 接口接口byte sign( 网上银行商户手册Copyright ICBC SDC 2005.8 - 7 -byte src, int srcLen, byte privateKey, char keyPass)。参数说明：src 为需要签名的数据，长度为：srcLen;privateKey 为其私钥keyPass 为私钥密码返回：成功：签名数据失败：返回空(null)注：src 源数据就是要进行签名的数据串信息。3然后调用然后调用 BASE64 编码编码 API 对产生的签名数据编码，接口如下：对产生的签名数据编码，接口如下：C 接口接口int bas

15、e64enc(unsigned char *src, int srcLen, char *dst, int *dstLen)参数说明：src 源数据，其长度为：srcLen;dst 为编码后的数据，长度存放在：dstLendst 的存储空间由接口申请，应用释放返回：0 正确，-1 错误JAVA 接口：接口：byte base64enc(byte src)参数说明：src 源数据返回：正确 编码后数据，错误 null注：src 源数据就是要进行 BASE64 编码的签名信息。4签名信息产生完毕。签名信息产生完毕。商户证书字段商户证书字段 cert 的的 BASE64 编码编码对商户证书的 BAS

16、E64 编码与对签名信息的 BASE64 的编码一样，在此不在赘述。1.3 一个链接例子一个链接例子以下给出商户网站到中国工商银行网上银行的“网上支付”链接的 form表单的例子（注意避免使用中文的全角符号） 网上银行商户手册Copyright ICBC SDC 2005.8 - 8 -（form 不能有 name 属性）（若不正确，将无银行反馈信息，注意不能省略http:/）（金额为不带小数点的到分的一个字符串，即“112390”代表的是“1123.90 元” ）（金额为不带小数点的到分的一个字符串，即“112390”代表的是“1123.90 元” ） 网上银行商户手册Copyright I

17、CBC SDC 2005.8 - 9 -2银行反馈信息的接口银行反馈信息的接口 客户通过中国工商银行 B2B 支付新接口进行电子支付是实时清算的, 银行需要经过收到支付信息余额确认划拨款项等环节才能将客户的款项划至收款人帐户中。不论支付成功还是失败或者支付过程中发生错误，银行都会将指令信息及时反馈给商户。目前 b2b 新接口只提供 URL 通知方式。由交易的网站（一般是卖方或者中间的电子商城）提供一个URL（Asp、Jsp、Java Bean 或者 CGI 等）供访问，我们使用 Form 提交方式将所有数据提交给该 URL，并将银行的电子签名作为数据项，提交给商户网站。2.1 通知消息接口数据

18、格式：通知消息接口数据格式：1. 编写编写 CGI 程序接收工行如下的程序接收工行如下的 http 请求请求工行通知商户的交易结果信息的内容由订单信息和订单支付结果信息组成如下格式(各个数各个数据项的值分别进行了据项的值分别进行了 URL 编码编码)：APIName=B2B&APIVersion=001.001.001.001&Shop_code=商户代码& MerchantURL =支付结果信息通知程序地址&Serial_no=指令序号&PayStatusZHCN=订单处理状态&TranErrorCode=错误代码&TranErrorM

19、sg=错误描述& ContractNo =订单号& ContractAmt=订单金额&Account_cur=001&JoinFlag=2&ShopJoinFlag=&CustJoinFlag=&CustJoinNumber=&NotifySign=订单签名数据(base64 编码)&SendType=结果发送类型& TranTime=接收交易日期时间&NotifyTime=返回通知日期时间& Shop_acc_num =商城账号& PayeeAcct =收款单位账号& PayeeN

20、ame =收款单位名称&ShopRem=商城备注字段通知信息各字段的定义：通知信息各字段的定义：变量名称变量名称变量命名变量命名长度定义长度定义说明说明接口名称APINameMAX (30)原输入值，签名接口版本号APIVersion=15原输入值，签名商户代码Shop_code=14原输入值，签名，唯一确定一个商户的代码，商户在工行开户时，由工行告知商户支付结果信息通知程序地址MerchantURLMAX (200)原输入值，签名，使用 HS 接口模式的商户用来接收工行订单支付结果信息的程序名字和位置 指令序号Serial_noMAX(18)必输，签名订单处理状态PayStatusZ

21、HCN=1必输，签名0-成功1-失败2-可疑交易3-等待授权错误代码TranErrorCodeMAX(5)必输，签名 网上银行商户手册Copyright ICBC SDC 2005.8 - 10 -错误描述TranErrorMsgMAX(200)必输，签名订单号ContractNoMAX(30)原输入值，签名，客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。订单金额ContractAmtMAX(18)原输入值，签名，客户支付订单的总金额，一笔订单一个，保留到分，无小数点，如金额为1.00 元，上传数据为“100”

22、支付币种Account_cur=3原输入值，签名，用来区分一笔支付的币种。目前工行只支持人民币（001）支付。定义如下：001 人民币检验联名标志JoinFlag=1原输入值，签名商城联名标志ShopJoinFlag=10：已与工行联名；1：未与工行联名（暂无该功能，预留），签名客户联名标志CustJoinFlag=10：已注册；1：未注册（暂无该功能，预留）签名联名会员号CustJoinNumberMAX(40)（暂无该功能，预留）签名订单签名数据NotifySign无限制必输，为字符串，已经过 Base64 编码，商户验证前需先解码结果发送类型SendType=10 -成功失败信息都发送1

23、 - 只发送成功信息原输入值，签名，如果取 0，工行向商户发送一笔订单的每一次交易结果，无论支付成功或者失败，如果取 1，工行只向商户发送交易成功的通知信息。当在付款人一方 b2b 支付指令经过指令批复后提交的，结果发送类型默认为成功失败都发送，这时不取商户上送的发送类型。接收交易日期时间TranTime=14原输入值，签名，YYYYMMDDHHmmss。与系统当前时间差为：前 1 小时，后 12 小时返回通知日期时间NotifyTime=14必输，签名，YYYYMMDDHHmmss。商城账号Shop_acc_numMAX (19)原输入值，签名收款单位账号PayeeAcctMAX (19)原

24、输入值，签名收款单位名称PayeeNameMAX (60)签名商城备注字段ShopRemMAX(100)原输入值，最多 100 字符注意：注意：1.当在付款人一方 b2b 支付指令经过指令批复后提交的，结果发送类型默认为成功失败都发送，这时不取商户上送的发送类型。2.当在付款人一方 b2b 支付指令经过指令批复后提交的，通知消息中接受交易的日期时间 TranTime 为空。 网上银行商户手册Copyright ICBC SDC 2005.8 - 11 -2.2 通知消息的通知消息的 form 格式：格式：（商城号码）（商城通知消息地址）（指令序号）(五位的错误码，成功指令此项为 0)(错误信息

25、，成功指令此项为空)（定单号） 网上银行商户手册Copyright ICBC SDC 2005.8 - 12 -2.3 通知消息处理过程通知消息处理过程假设商户订单提供的通知信息的 URL 如下：http:/www.toICBC 80） ，则订单支付成功后，工商银行会自动向该地址发 http 请求，请求的 URL 如下：http:/www.toICBC MerchantURL =支付结果信息通知程序地址&Serial_no=指令序号&PayStatusZHCN=订单处理状态&TranErrorCode=错误代码&TranErrorMsg=错误描述& Co

26、ntractNo =订单号& ContractAmt=订单金额&Account_cur=001&JoinFlag=2&ShopJoinFlag=&CustJoinFlag=&CustJoinNumber=&NotifySign=订单签名数据(base64 编码)&SendType=结果发送类型& TranTime=接收交易日期时间&NotifyTime=返回通知日期时间& Shop_acc_num =商城账号& PayeeAcct =收款单位账号& PayeeName =收款单位名称&

27、;ShopRem=商城备注字段商城网站接收到该请求，取出数字签名信息，先使用工行提供的 API 对数字签名进行Base64 解码，然后使用工行提供的 API 验证签名，如果签名验证正确，说明该笔通知信息有效。商户应根据自己的业务逻辑对交易通知信息进行处理（注意：这里的交易通知信息可能为失败也可能为成功，而且一笔订单可能会产生多笔通知信息，但最多只可能有一个成功通知信息） 。通知消息中的的签名信息的产生（使用工商银行私钥签名）和 BASE64 编码的实现由工行交易平台产生，商户不需要关心；商户要关心的是如何对通知信息中的签名信息BASE64 解码，然后用工行的证书验证签名。验证签名信息验证签名信

28、息签名信息 NotifySign 的验证要经过如下几个步骤：1 取原始数据：取原始数据：原始数据为：APIName=接口名称&APIVersion=接口版本号&Shop_code=商户代码&MerchantURL=支付结果信息通知程序地址&Serial_no=指令序号&PayStatusZHCN=订单处理状态&TranErrorCode=错误代码&TranErrorMsg=错误描述&ContractNo=订单号&ContractAmt=订单金额&Account_cur=支付币种&JoinFlag=检验联名标

29、志&ShopJoinFlag=商城联名标志&CustJoinFlag=客户联名标志&CustJoinNumber=联名会员号&SendType=结果发送类型&TranTime=接收交易日期时间&NotifyTime=返回通知日期时间&Shop_acc_num=商城账号&PayeeAcct=收款单位账号&PayeeName=收款单位名称2取签名数据：取签名数据：签名数据：签名数据就是以 NotifySign 为属性名的属性值，它们以NotifySign =“签名信息”的形式在 http 请求中存在。3 调用调用 API 统一

30、接口对签名数据进行统一接口对签名数据进行 BASE64 解码，得到签名信息。接口如下：解码，得到签名信息。接口如下：C 接口接口 网上银行商户手册Copyright ICBC SDC 2005.8 - 13 -int base64dec(char *src, int srcLen, unsigned char *dst, int *dstLen)参数说明：src 源数据，其长度为：srcLen;dst 为编码后的数据，长度存放在：dstLendst 的存储空间由接口申请，应用释放返回：0 正确，-1 错误JAVA 接口接口byte base64dec(byte src)参数说明：src 源数据返回：正确 编码后数据，错误 null