中国某银行网上银行网上支付接口规范

1、网上银行商户手册PAGE 第28页 共28页网上银行商户手册 B2C支付付接口v1.00.0.3商户手册商户手册中国工商银银行软件件开发中中心Copyrrighht Resservved目录TOC o 1-3 h z u HYPERLINK l _Toc173203224 第 1 章章业务说说明 PAGEREF _Toc173203224 h 3 HYPERLINK l _Toc173203225 第 2 章章商户接接口 PAGEREF _Toc173203225 h 4 HYPERLINK l _Toc173203226 2.1支支付接口口 PAGEREF _Toc173203226 h 5

2、 HYPERLINK l _Toc173203227 2.1.11支付接接口表单单定义 PAGEREF _Toc173203227 h 5 HYPERLINK l _Toc173203228 2.1.22traanDaata数数据定义义 PAGEREF _Toc173203228 h 6 HYPERLINK l _Toc173203229 2.1.33traanDaata格格式定义义 PAGEREF _Toc173203229 h 7 HYPERLINK l _Toc173203230 2.1.44表单样样例 PAGEREF _Toc173203230 h 8 HYPERLINK l _Toc

3、173203231 2.2通通知接口口 PAGEREF _Toc173203231 h 9 HYPERLINK l _Tooc177320032332 2.22.1通知接接口表单单定义 PAGEREF _Toc173203232 h 9 HYPERLINK l _Toc173203233 2.2.22nottifyyDatta数据据定义 PAGEREF _Toc173203233 h 10 HYPERLINK l _Toc173203234 2.2.33nottifyyDatta格式式定义 PAGEREF _Toc173203234 h 11 HYPERLINK l _TToc11732203

4、2235 2.22.4表单样样例 PAGEREF _Toc173203235 h 11 HYPERLINK l _Toc173203236 2.3说说明 PAGEREF _Toc173203236 h 12 HYPERLINK l _Toc173203237 第 3 章章安全APPI说明明 PAGEREF _Toc173203237 h 13 HYPERLINK l _Toc173203238 第 4 章章开发步步骤 PAGEREF _Toc173203238 h 13业务说明B2C在线线支付接接口实现现工行个人人网银客客户在工工行B22C商户户网站进进行消费费支付的的业务处处理。新的1.0.

5、00.3版版本同原原先版本本的主要要区别在在于通知知消息方方式的改改变。原0版本和和1.00.0.1版本本（扩充充语言字字段以支支持英文文版）在在订单中中要求商商户选择择通知方方式，即即1、需需要银行行通知交交易结果果，2、不不需要银银行通知知交易结结果而是是商户主主动查询询；当需要要通知时时，需要要在订单单中提供供商户接接收银行行通知地地址，当当银行处处理结束束后，会会在银行行的后台台服务器器请求商商户的此此地址，将将交易结结果用hhttpp连接ppostt表单形形式提交交给商户户，然后后返回客客户交易易结果页页面。新的1.00.0.3版本本不再要要求商户户选择通通知方式式，和

6、接收银银行通知知的地址址；此版版本要求求商户在在提交订订单时，提提供交易易处理后后返回商商户的地地址，即即完成客客户从商商户转向向到银行行进行支支付，处处理后又又从银行行定向回回商户网网站的闭闭环。在在从银行行交易页页面返回回商户时时，将交交易结果果作为表表单数据据提交到到商户此此返回地址址。处理的优点点：1、强强制完成成交易闭闭环；22、无需需银行后后台发送送通知，客客户不需要等等待商户户接收银银行通知知后才能能看到交交易结果果页面，缩缩短响应应时间；3、通通知方式式不再局局限于hhttpp连接和和80端端口，返返回商户户的地址址可以使使用htttpss方式和和其他商商户支持持的端口口，提高

7、高安全性性；4、银银行作为为交易的的一方，支支持众多多商户和和客户时时，存在在一定的的带宽和和服务器器处理压压力，使使用客户户返回商商户方式式提供交交易结果果，可有有效减少少交易掉掉单现象象，只要要客户到到了银行行的结果果页面，如如果还出出现掉单单问题，则则可能是是客户和和商户的的通讯等等方面的的问题。以下简述处处理流程程：客户在商户户网站浏浏览商品品信息，签签订订单单；商户按照工工行B2C支付付1.00.0.3接口口形成提提交数据据，并使使用工行行提供AAPI和和商户证证书对订订单数据据签名，形形成foorm表表单返回回客户浏浏览器，表表单acctioon地址址指向工工行接收收商户订订单信息

8、息的seervllet；客户确认使使用工行行支付后后，提交交此表单单到工行行；工行网银系系统接收收此笔订订单，对对订单信信息和商商户信息息进行检检查；通过检查则则显示工工行支付付页面，1.00.0.3版本本会提示示客户输输入交易易卡号；客户输入后后提交；银行查询客客户相关关信息；返回客户在在银行的的预留信信息；客户确认；返回交易确确认页面面；不同类型客客户使用用各自认认证方式式进行交交易确认认，支持持静态支支付密码码、动态态口令卡卡、证书书签名；银行校验后后进行支支付处理理；将结果形成成通知消消息并有有银行端端签名信信息，返返回客户户端；引导客户返返回商户户网站，地地址是订订单中提提供的商商户

9、urrl，此此urll支持hhttpp和htttpss及自定定义端口口；B2C在线线支付接接口版本本说明：1.0.00.0（基基本支付付）1.0.00.1（支支持英文文界面）1.0.00.2（内内部保留留）1.0.00.3（保保留1.0.00.1功功能，优优化通知知方式）1.0.00.4（商商户订单单中指定定支付卡卡，不强强制使用用e卡支付付，不允允许客户户的支付付卡透支支支付，专门用用于基金金商户进进行基金金直销业业务，同同1.00.0.3通知知方式）通知消息模模式区别别：原有模式：支付处处理后，后后台发送送商户通通知；新增模式：支付完完成后或客户户点击“返回商商户”，利用用客户浏浏览器跳跳

10、转，完完成商户户通知的的转发，后后台不再再单独发发送商户户通知。对于不同类类型商户户接口区区别：对于购物类类型商城城只支持持使用1.0.00.0/1.00.0.1/3对于基金直直销类型型网站商商城只支支持使用用1.00.0.4商户接口接口定义通通过接口口名称和和接口版版本号来来标识，以以便将来来的扩展展；新通通知方式式的B22C接口口称为新新模式BB2C接口口；原有有后台发发送htttp通通知的方方式称为为原模式式接口；支付接口支付接口表表单定义义新模式接口口的交易易数据整整合到一一个xmml格式式串，作作为表单单的一项项整体提提交，不不再同原原来每个个字段都都是keey-vv

11、aluue形式式；FORM表表单数据据如下：变量名称变量命名长度定义说明接口名称interrfacceNaameMAX(330)必输，取值：“IICBCC_PEERBAANK_B2CC”接口版本号号interrfacceVeersiionMAX(115)必输，取值：“”交易数据tranDDataa无限制必输，签名名；整合所有交交易数据据形成的的xmll明文串，并做做BASSE644编码；具体格式定定义见下下文；注意：需有xmll头属性性；整个个字段使使用BAASE664编码码；xml明文文中没有有回车换换行和多余空空格；订单签名数数据merSiignMMsg无限制必输，商户使用

12、工工行提供供的签名名APII和商户户证书将将traanDaata的的xmll明文串串进行签签名，得得到二进进制签名名数据，然然后进行行BASSE644编码后后得到可可视的merrSiggnMssg；注意：签名名时是针针对trranDDataa的xmml明文文，不是是将trranDDataa进行BBASEE64编编码后的的串；商城证书公公钥merCeert无限制必输，商户用二进进制方式式读取证证书公钥钥文件后后，进行行BASSE644编码后后产生的的字符串串；注：1、数据中中不能包包含“|”、“&”、“=”，这些些字符为为银行端端程序保保留字符符；中文文变量使使用GBBK编码码。 2、从商户户P

13、osst过来来的数据据，参数数名的名名称必须须与上表表中完全全相同，名名称中的的字母大大小写均均要相同同，不能能进行随随意更改改(在fformm中的提提交按钮钮中中subbmitt不能有有Namme属性性)；此此外，如如果其他他inpput 项的NNamee中使用用了双引引号，如如：，则则一定注注意在引引号内不不要包含含空格，不不要写成成“merr URRL ”，如果果拼写错错误或者者多了空空格，将将造成数数据无法法识别，无无法正常常进行支支付3、接口名名称和版版本号一一定要和和上表中中相同.。4、商户提提交数据据中的空空格将被被认为是是有效字字符被接接收，请请商户开开发时注注意对多多余空格格

14、的控制制。5、traanDaata交交易数据据的xmml串需需要有xxml的的头，即即tranDDataa数据定定义变量名称变量命名长度定义说明接口名称interrfacceNaame16必输，取值：“IICBCC_PEERBAANK_B2CC”接口版本号号interrfacceVeersiionMAX(115)必输，取值：“”交易日期时时间orderrDatte=14必输，格式为：YYYYYYMMDDDHHHmmsss要求在银行行系统当当前时间间的前11小时和和后122小时范范围内，否否则判定定交易时时间非法法。订单号orderridMAX(330)必输，客户支付后后商户网网

15、站产生生的一个个唯一的的定单号号，该订订单号应应该在相相当长的的时间内内不重复复。工行行通过订订单号加加订单日日期来唯唯一确认认一笔订订单的重重复性。订单金额amounntMAX(110)必输，客户支付订订单的总总金额，一一笔订单单一个，以以分为单单位。不不可以为为零，必必需符合合金额标标准。支付币种curTyype= 3必输，用来区分一一笔支付付的币种种，目前前工行只只支持使使用人民民币（0001）支支付。取值： “0011”商户代码merIDDMAX(220)必输，唯一确定一一个商户户的代码码，由商商户在工工行开户户时，由由工行告告知商户户。商户账号merAccctMAX(119)必输，商

16、户入账账账号，只只能交易易时指定定。（商商户付给给银行手手续费的的账户，可可以在开开户的时时候指定定，也可可以用交交易指定定方式；用交易易指定方方式则使使用此商商户账号号）检验联名标标志veriffyJooinFFlagg=1必输， 取值“1”：客户户支付时时，网银银判断该该客户是是否与商商户联名名，是则则按上送送金额扣扣帐，否否则展现现未联名名错误；取值“0”：不检检验客户户是否与与商户联联名，按按上送金金额扣帐帐。语言版本LanguuageeMAX(110)选输，默认认为中文文版取值：“EEN_UUS”为英文文版；取值：“ZZH_CCN”或其他他为中文文版。注意：大小小写敏感感。商品编号g

17、oodssIDMAX(330)选输商品名称goodssNammeMAX(660)选输商品数量goodssNummMAX(110)选输已含运费金金额carriiageeAmttMAX(110)选输商城提示merHiintMAX(1120)选输备注字段11remarrk1MAX(1100)选输 单位位：字节节备注字段22remarrk2MAX(1100)选输 单位位：字节节返回商户UURLmerURRLMAX(110244)必输必须合法的的URLL，交易易结束，将将客户引引导到商商户的此此urll，即通通过客户户浏览器器posst交易易结果信信息到商商户的此此URLL返回商户变变量merVAARM

18、AX(110244)选输商户自定义义，当返返回银行行结果时时，作为为一个隐隐藏域变变量，商商户可以以用此变变量维护护sesssioon等等等。由客客户端浏浏览器支支付完成成后提交交通知结结果时是是明文传传输，建建议商户户对此变变量使用用额外安安全防范范措施，如如签名、bbasee64tranDDataa格式定定义tranDDataa格式(xmll格式固固定，选选输字段段的取值值可以为为空，标标签需保保留)表单样例表单数据：tranDDataa对应的的xmll明文：ICCBC_PERRBANNK_BB2C32200770722510050114200070072551055014

19、4-2113400625548220000102000ECC200000887502200002044090015002911300ZHH_CNN0001威威尼熊2200请请保留包包装htttp:/loocallhosst:990811/Neewb22c_PPay_Merr.jssptesst通知接口通知接口表表单定义义变量名称变量命名长度定义说明返回商户变变量merVAAR无限制取值：商户户提交接接口中mmerVVAR字字段当返返回银行行结果时时，作为为一个隐隐藏域变变量，商商户可以以用此变变量维护护sesssioon等等等。由客客户端浏浏览器支支付完成成后提交交通知结结果时是是明文传传输，

20、建建议商户户对此变变量使用用额外安安全防范范措施，如如签名、bbasee64，银行端端将此字字段原样样返回通知结果数数据notiffyDaata无限制银行通知消消息，xxml格格式定义义见下文文，提交商商户时对对xmll明文串串进行了了basse644编码；xml串中中没有回回车换行行和多余余空格；包含xxml头头属性，且且格式固固定；银行对通知知结果的的签名数数据signMMsg无限制银行使用自自己证书书对商户户通知消消息nootiffyDaata字字段的xxml格格式明文文串进行行的签名名，然后进进行BAASE664编码码后的字字符串。注意：签名名是对nnotiifyDDataa的xmml

21、明文文进行签签名，不不是其BBASEE64编编码后的的串；签签名后得得到二进进制数据据，对此此数据进进行BAASE664编码码得到ssignnMsggnotiffyDaata数数据定义义变量名称变量命名长度定义说明接口名称interrfacceNaame16取值：“IICBCC_PEERBAANK_B2CC”接口版本号号interrfacceVeersiionMAX(115)取值：“”交易日期时时间orderrDatte=14格式为：YYYYYYMMDDDHHHmmsss要求在银行行系统当当前时间间的前11小时和和后122小时范范围内，否否则判定定交易时时间非法法。订单号ord

22、erridMAX(330)客户支付后后商户网网站产生生的一个个唯一的的定单号号，该订订单号应应该在相相当长的的时间内内不重复复。工行行通过订订单号加加订单日日期来唯唯一确认认一笔订订单的重重复性。订单金额amounntMAX(110)客户支付订订单的总总金额，一一笔订单单一个，以以分为单单位。不不可以为为零，必必需符合合金额标标准。支付币种curTyype= 3用来区分一一笔支付付的币种种，目前前工行只只支持使使用人民民币（0001）支支付。取值： “0011”商户代码merIDDMAX(220)唯一确定一一个商户户的代码码，由商商户在工工行开户户时，由由工行告告知商户户。商户账号merAcc

23、ctMAX(119)商户收费入入账账号号 （只只能交易易时指定定）。检验联名标标志veriffyJooinFFlagg=1取值“1”：客户户支付时时，网银银判断该该客户是是否与商商户联名名，是则则按上送送金额扣扣帐，否否则展现现未联名名错误；取值“0”：不检检验客户户是否与与商户联联名，按按上送金金额扣帐帐。客户联名标标志JoinFFlagg=1客户在银行行端是否否与商城城联名标标志位。11客户联联名 00客户未未联名联名会员号号UserNNumMAX(440)联名客户在在商户的的会员号号。银行指令序序号TranSSeriialNNoMAX(330)银行端指令令流水号号返回通知日日期时间间no

24、tiffyDaateMAX(114)格式为：YYYYYYMMDDDHHHmmsss订单处理状状态tranSStatt=11-“交易易成功，已已清算”；2-“交易易失败”；3-“交易易可疑”错误描述commeentMAX(1100)错误描述notiffyDaata格格式定义义notiffyDaata格格式(xxml格格式固定定，选输输字段的的取值可可以为空空，标签签需保留留)表单样例表单数据：notiffyDaata对对应的明明文：ICBBC_PPERBBANKK_B22C322007707225100501142000700725510550144-21134006255482

25、20000102000ECC2000008875022000020440900150029113002000707725111044001交易易成功！说明商户可能收收到的银银行通知知指令成功：只能有一笔笔成功、且且要验证证银行签签名、订订单金额额等信息息是否与与商户端端记录一一致。指令失败：注意可能收收到多笔笔失败。客客户支付付失败时时可以重重提此笔笔订单到到银行支支付。指令可疑：由于网银系系统与后后台业务务处理系系统间通通讯异常常，造成成网银不不能确认认支付指指令结果果，则此此笔指令令为可疑疑指令；可疑指指令将被被自动批批复，商商户、客客户可于于第二日日查询指指令状态态。没有收到客客户浏览览

26、器转发发的银行行通知：由于客户浏浏览器端端或互联联网通讯讯等原因因可能造造成商户户端接收收不到客客户浏览览器提交交的银行行通知。当当没有收收到银行行通知时时，可登登录工行行商户服服务网站站手工查查询指令令状态或或者商户户调用查查询接口口自动处处理。商户提交的的订单信信息和银银行返回回的通知知消息都都是xmml串，并并且进行行了BAASE664编码码；提交和返回回的xmml都应应有xmml头；安全APII说明为了保证商商户提交交订单数数据和银银行通知知信息数数据的完完整性，不不可抵赖赖性，现现提供一一套用于于信息签签名、验验签和BBASEE64编编解码的的函数。商商户开发发时使用用这套函函数和工工行颁发发的商户户证书进进行商户户订单信信息签名名；签名名数据项项和顺序序均固定定，具体体格式可可参见上上文的数据据定义；同时使使用这套套APII和银行行公钥可可以验证证银行通通知消息息的有效效性。安安全APPI的使使用方法法可参见见相关开发发语言的的说