中国工商银行网上银行新B2C在线支付接口说明V1.0.0.11

更新时间：2024-01-05 01:35:01 阅读量：教育文库文档下载

说明：文章内容仅供预览，部分内容可能不全。下载后的文档，内容与下面显示的完全一致。下载之前请确认下面内容是否您想要的，是否完整无缺。

中国工商银行个人网上银行推荐度：
相关推荐

网上银行商户手册

B2C支付接口v1.0.0.11

商户手册中国工商银行软件开发中心 Copyright Reserved

网上银行商户手册

第 1 章第 2 章

2.1 2.1.1 2.1.2 2.1.3 2.1.4 业务说明 ....................................................................................................................... 3 商户接口 ....................................................................................................................... 4 支付接口 ....................................................................................................................... 4 支付接口表单定义 ................................................................................................... 4 tranData数据定义 .................................................................................................. 6 tranData格式定义 .................................................................................................. 8 表单样例 ................................................................................................................... 9 2.2 2.2.1 2.2.2 2.2.3 2.2.4 2.3 第 3 章第 4 章

通知接口 ..................................................................................................................... 11 通知接口表单定义 ................................................................................................. 11 notifyData数据定义 ............................................................................................ 12 notifyData格式定义 ............................................................................................ 13 表单样例 ................................................................................................................. 14 说明 ............................................................................................................................. 15 安全API说明 ............................................................................................................ 15 开发步骤 ..................................................................................................................... 15

第 2 页共 16 页

网上银行商户手册

第 1 章业务说明

以下简述处理流程：

4、校验商户签名和证书、订单数据、商户状态等7、检查客户信息指令主机发12、主机14、将结果返回商户商户13、返回客户支付结果3、客户将订单数据提交银行返回客户支付页面5、回显订单指定卡号或提示客户输入卡号6、客户确定提交网银1、客户浏览商户网站并下订单2、商户使用API证书对订单签名并返回客户端8、返回预留信息9、客户确认10、返回确认页面11、客户确认（静态密码、动态密码、签名）客户

1. 客户在商户网站浏览商品信息，签订订单；

2. 商户按照工行B2C支付1.0.0.11接口形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接收商户订单信息的servlet；

3. 客户确认使用工行支付后，提交此表单到工行；

4. 工行网银系统接收此笔订单，对订单信息和商户信息进行检查；

5. 通过检查则显示工行支付页面，1.0.0.11版本会提示客户输入交易卡号； 6. 客户输入后提交；

7. 银行查询客户相关信息； 8. 返回客户在银行的预留信息； 9. 客户确认；

10. 返回交易确认页面；

11. 不同类型客户使用各自认证方式进行交易确认，支持静态支付密码、动态口令卡、证书签名；

12. 银行校验后进行支付处理；

13. 工行进行支付指令处理后，如果商户需要工行实时通知，则工行将处理结果使用http协议post方式将通知消息数据提交到商户网站（这个接收银行通知消息的商户端地址是随商

第 3 页共 16 页

网上银行商户手册

户订单数据提交银行的merURL字段），商户返回取货地址或关闭这个银行与其建立的连接后，银行才显示交易结果页面给客户。（注意1、发送通知和显示结果页面是串行的，所以商户端接收银行通知处理时间太长可能导致客户等待超时，造成银行不能将交易结果页面显示给客户。2、此连接是银行服务器自动和商户进行的连接，商户返回也是直接返回给银行，商户端不能对银行的这个请求进行重定向。）

14. 工行进行支付指令处理后，如果商户不需要工行实时通知，则工行直接显示交易结果给客户。

B2C在线支付接口版本说明： 1.0.0.0（基本支付）

1.0.0.1（支持中英文界面） 1.0.0.2（内部保留）

1.0.0.3（保留1.0.0.1功能，优化通知方式）

1.0.0.4（商户订单中指定支付卡，不强制使用e卡支付，不允许客户的支付卡透支支付，专门用于基金商户进行基金直销业务，同1.0.0.3通知方式）

1.0.0.5（基于1.0.0.1，在原有接口基础上扩展支持红利卡，支持红利卡的商户采用；当上送项不支持红利卡的时候，接口等同于1.0.0.1）

1.0.0.6（基于1.0.0.3，在原有接口基础上扩展支持红利卡，支持红利卡的商户采用；当上送项不支持红利卡的时候，接口等同于1.0.0.3）

1.0.0.7（基于1.0.0.3，在原有接口基础上扩展支持同时上送5笔订单，即支持购物车模式，支持商户主动分期付款模式，当商户选择1期和1笔订单的时候，功能等同于1.0.0.3接口） 1.0.0.8（基于1.0.0.3，在原有接口基础上扩展，根据商户上送的是否允许透支标志来控制是否运行客户使用信用卡进行支付，同1.0.0.3通知方式）

1.0.0.9（基于1.0.0.3，在原有接口基础上优化商户校验及接口并发性，同1.0.0.0通知方式） 1.0.0.10（基于1.0.0.8，同1.0.0.0通知方式）

1.0.0.11（基于1.0.0.7，在原有接口基础上增加1.0.0.8的透支标志控制，增加商户上送数据,丰富及扩展用户体验，增加校验商户域名，同1.0.0.0通知方式）

第 2 章商户接口 2.1 支付接口

2.1.1 支付接口表单定义

新模式接口的交易数据整合到一个xml格式串，作为表单的一项整体提交，不再同原来每个字段都是key-value形式；

FORM表单数据如下：变量名称接口名称变量命名 interfaceName 长度定义 MAX(30) 说明必输，取值：“ICBC_PERBANK_B2C” 第 4 页共 16 页

网上银行商户手册

接口版本号交易数据 interfaceVersion MAX(15) tranData 无限制必输，取值：“1.0.0.11” 必输，签名；整合所有交易数据形成的xml明文串，并做BASE64编码；具体格式定义见下文；注意：需有xml头属性；整个字段使用BASE64编码； xml明文中没有回车换行和多余空格；必输，商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg；注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串；必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串；订单签名数据 merSignMsg 无限制商城证书公钥 merCert 无限制注：

1、数据中不能包含“|”、“&”、“=”，这些字符为银行端程序保留字符；中文变量使用GBK编码。

2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：

4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。

5、tranData交易数据的xml串需要有xml的头，即

standalone=\

第 5 页共 16 页

网上银行商户手册

2.1.2 tranData数据定义

变量名称接口名称接口版本号交易日期时间变量命名 interfaceName interfaceVersion orderDate 长度定义＝16 MAX(15) =14 说明必输，取值：“ICBC_PERBANK_B2C” 必输，取值：“1.0.0.11” 必输，格式为：YYYYMMDDHHmmss 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。必输，每笔订单都需要有不同的订单号；客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。必输，每笔订单一个；客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。必输，每笔订单一个；取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。必输，每笔订单一个，可以相同；商户入账账号，只能交易时指定。（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）选输，每笔订单一个；必输，每笔订单一个；选输，每笔订单一个；选输，每笔订单一个；必输，取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。第 6 页共 16 页

订单号 orderid MAX(30) 订单金额 amount MAX(10) 分期付款期数 installmentTimes MAX（2）商户账号 merAcct MAX(19) 商品编号商品名称商品数量已含运费金额检验联名标志 goodsID goodsName goodsNum carriageAmt verifyJoinFlag MAX(30) MAX(60) MAX(10) MAX(10) =1 网上银行商户手册

语言版本 Language MAX(10) 选输，默认为中文版取值：“EN_US”为英文版；取值：“ZH_CN”或其他为中文版。注意：大小写敏感。必输，用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001” 必输，唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。必输默认“2”。取值范围为0、1、2，其中0表示仅允许使用借记卡支付，1表示仅允许使用信用卡支付，2表示借记卡和信用卡都能对订单进行支付必输在交易转账处理完成后把交易结果通知商户的处理模式。取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段；取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的B2C商户服务网站，或者使用工行提供的客户端程序API主动获取通知信息。选输取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1”，银行只向商户发送交易成功的通知信息。只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。选输，上送商户网站域名，如果上送，工行会在客户支付订单时，校验商户上送域名与客户跳转工行支付页面之前网站域名的一致性。选输，工行在支付页面显示该信息。必输第 7 页共 16 页

支付币种 curType = 3 商户代码 merID MAX(20) 支持订单支付的银行卡种类 creditType = 1 通知类型 notifyType = 2 结果发送类型 resultType =1 商户reference merReference MAX(200) 客户端IP 虚拟商品/实merCustomIp goodsType MAX(20) =1 网上银行商户手册

物商品标志位买家用户号买家联系电话收货地址订单备注商城提示备注字段1 备注字段2 merCustomID merCustomPhone goodsAddress merOrderRemark merHint remark1 remark2 MAX(100) MAX(20) MAX(200) MAX(200) MAX(120) MAX(100) MAX(100) MAX(1024) 取值“0”：虚拟商品；取值“1”，实物商品。选输选输，当商户上送goodsType值为“0”，该项必输选输，当商户上送goodsType值为“1”，该项必输选输，工行在支付页面显示该信息。选输选输单位：字节选输单位：字节必输必须合法的URL，交易结束，将客户引导到商户的此url，即通过客户浏览器post交易结果信息到商户的此URL 选输商户自定义，当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64 返回商户URL merURL 返回商户变量 merVAR MAX(1024) 注：红色字体部分内容，每笔订单都有一份。

2.1.3 tranData格式定义

tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)

ICBC_PERBANK_B2C 1.0.0.11 20100308141629 001 0200EC20001119 201003081416290 1 1 0200026009018372212 001

第 8 页共 16 页

网上银行商户手册

威尼熊 2 20 201003081416291 1 1 0200026009018372212 001 威尼熊 2 20 0 ZH_CN 2 AG 1 localhost 127.0.0.1 1 123456 13466780886 三里屯防欺诈接口专用请保留包装 http://localhost:9080/EbizSimulate/emulator/Newb2c_Pay_Mer.jsp test

注：红色字体部分，即是循环部分，最大5次，超过则接口校验报错。

2.1.4 表单样例

表单数据：

第 9 页共 16 页

网上银行商户手册

tranData对应的xml明文：

第 10 页共 16 页

网上银行商户手册

standalone=\ersion>1.0.0.11201003081416290010200EC20001119201003081416290110200026009018372212001威尼熊220201003081416291110200026009018372212001威尼熊

2200ZH_CN2AG1localhost127.0.0.1112345613466780886三里屯

防欺诈接口专用请保留包装http://localhost:9080/EbizSimulate/emulator/Newb2c_Pay_Mer.jsptest

2.2 通知接口

2.2.1 通知接口表单定义

变量名称返回商户变量变量命名 merVAR 长度定义无限制说明取值：商户提交接口中merVAR字段当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64，银行端将此字段原样返回银行通知消息，xml格式定义见下文，提交商户时对xml明文串进行了base64编码； xml串中没有回车换行和多余空格；包含xml头属性，且格式固定；银行使用自己证书对商户通知消息notifyData字段的xml格式明文串进行的签名，然后进行BASE64编码后的字符串。注意：签名是对notifyData的xml明第 11 页共 16 页

通知结果数据 notifyData 无限制银行对通知结果的签名数据 signMsg 无限制网上银行商户手册

文进行签名，不是其BASE64编码后的串；签名后得到二进制数据，对此数据进行BASE64编码得到signMsg

2.2.2 notifyData数据定义

变量名称接口名称接口版本号交易日期时间变量命名 interfaceName interfaceVersion orderDate 长度定义＝16 MAX(15) =14 说明取值：“ICBC_PERBANK_B2C” 取值：“1.0.0.11” 格式为：YYYYMMDDHHmmss 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。必输，每笔订单一个；取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。商户收费入账账号（只能交易时指定）。用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001” 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。客户在银行端是否与商城联名标志位。1客户联名 0客户未联名联名客户在商户的会员号。银行端指令流水号第 12 页共 16 页

订单号 orderid MAX(30) 订单金额 amount MAX(10) 分期付款期数 installmentTimes MAX（2）商户账号支付币种 merAcct curType MAX(19) = 3 商户代码检验联名标志 merID verifyJoinFlag MAX(20) =1 客户联名标志 JoinFlag =1 联名会员号银行指令序号 UserNum MAX(40) MAX(30) TranSerialNo 网上银行商户手册

批次号返回通知日期时间订单处理状态 TranBatchNo notifyDate tranStat MAX(15) MAX(14) =1 银行端为多笔一次提交的指令生成一个唯一的批次号格式为：YYYYMMDDHHmmss 1-“交易成功，已清算”； 2-“交易失败”； 3-“交易可疑” 错误描述错误描述 comment MAX(100) 注：红色字体部分内容，每笔订单都有一份。

2.2.3 notifyData格式定义

notifyData格式(xml格式固定，选输字段的取值可以为空，标签需保留)

…

第 13 页共 16 页

网上银行商户手册

注：红色字体部分，即是循环部分，最大5次，根据商户上送的数量返回。

2.2.4 表单样例

表单数据：

notifyData对应的明文：

1.0.0.11200707251050140010200EC2000087520070725105014-2134062548200

tallmentTimes>1020002040901502913020070725105014-21340625493003020002040901502913120070725105014-2134062550600602000204090150291300200707251050149200707251104001

mment>交易成功！

第 14 页共 16 页

网上银行商户手册

2.3 说明

商户可能收到的银行通知指令成功：

只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。指令失败：

商户只能收到一笔客户放弃支付返回商城的信息。指令可疑：

由于网银系统与后台业务处理系统间通讯异常，造成网银不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。

没有收到客户浏览器转发的银行通知：

由于客户浏览器端或互联网通讯等原因可能造成商户端接收不到客户浏览器提交的银行通知。当没有收到银行通知时，可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。

商户提交的订单信息和银行返回的通知消息都是xml串，并且进行了BASE64编码；提交和返回的xml都应有xml头；

第 3 章安全API说明

为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上文的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。安全API的使用方法可参见相关开发语言的说明和demo程序；

第 4 章开发步骤

商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。生成订单：

1、商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户

证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；

2、商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和

扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名）

3、商户进行开发，准备要求的订单数据；

4、其中订单签名数据merSignMsg字段是对明文的签名数据；需要使用提供的API函数和

商户私钥进行签名，得到签名串，然后做BASE64编码；

5、其中商城证书公钥merCert字段需要使用API函数做BASE64编码； 6、准备好订单数据，即完成订单提交的开发；之后只要将订单提交银行接收入口“https://

第 15 页共 16 页

网上银行商户手册