中国工商银行网上银行BC在线支付接口说明新版本

B2C支付接口v1.0.0.3商户手册中国工商银行软件开发中心Copyright Reserved目录第 1 章业务阐明3第 2 章商户接口42.1支付接口52.1.1支付接口表单定义52.1.2tranData数据定义62.1.3tranData格式定义72.1.4表单样例82.2告知接口92.2.1告知接口表单定义92.2.2notifyData数据定义102.2.3notifyData格式定义112.2.4表单样例112.3阐明12第 3 章安全API阐明13第 4 章开发环节13第 1 章 业务阐明B2C在线支付接口实现工行个人网银客户在工行B2C商户网站进行消费支付的业务解决。新的1.0.0.3版本同原先版本的重要区别在于告知消息方式的变化。原1.0.0.0版本和1.0.0.1版本（扩大语言字段以支持英文版）在订单中规定商户选择告知方式，即1、需要银行告知交易成果，2、不需要银行告知交易成果而是商户积极查询；当需要告知时，需要在订单中提供商户接受银行告知地址，当银行解决结束后，会在银行的后台服务器祈求商户的此地址，将交易成果用http连接post表单形式提交给商户，然后返回客户交易成果页面。新的1.0.0.3版本不再规定商户选择告知方式，和接受银行告知的地址；此版本规定商户在提交订单时，提供交易解决后返回商户的地址，即完毕客户从商户转向到银行进行支付，解决后又从银行定向回商户网站的闭环。在从银行交易页面返回商户时，将交易成果作为表单数据提交到商户此返回地址。解决的长处：1、强制完毕交易闭环；2、无需银行后台发送告知，客户不需要等待商户接受银行告知后才干看到交易成果页面，缩短响应时间；3、告知方式不再局限于http连接和80端口，返回商户的地址可以使用https方式和其她商户支持的端口，提高安全性；4、银行作为交易的一方，支持众多商户和客户时，存在一定的带宽和服务器解决压力，使用客户返回商户方式提供交易成果，可有效减少交易掉单现象，只要客户到了银行的成果页面，如果还浮现掉单问题，则也许是客户和商户的通讯等方面的问题。如下简述解决流程：1. 客户在商户网站浏览商品信息，签订订单；2. 商户按照工行B2C支付1.0.0.3接口形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接受商户订单信息的servlet；3. 客户确认使用工行支付后，提交此表单到工行；4. 工行网银系统接受此笔订单，对订单信息和商户信息进行检查；5. 通过检查则显示工行支付页面，1.0.0.3版本会提示客户输入交易卡号；6. 客户输入后提交；7. 银行查询客户有关信息；8. 返回客户在银行的预留信息；9. 客户确认；10. 返回交易确认页面；11. 不同类型客户使用各自认证方式进行交易确认，支持静态支付密码、动态口令卡、证书签名；12. 银行校验后进行支付解决；13. 将成果形成告知消息并有银行端签名信息，返回客户端；14. 引导客户返回商户网站，地址是订单中提供的商户url，此url支持http和https及自定义端口；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.0/1.0.0.1/1.0.0.3对于基金直销类型网站商城只支持使用1.0.0.4第 2 章 商户接口接口定义通过接口名称和接口版本号来标记，以便将来的扩展；新告知方式的B2C接口称为新模式B2C接口；原有后台发送http告知的方式称为原模式接口；2.1 支付接口2.1.1 支付接口表单定义新模式接口的交易数据整合到一种xml格式串，作为表单的一项整体提交，不再同本来每个字段都是key-value形式；FORM表单数据如下：变量名称变量命名长度定义阐明接口名称interfaceNameMAX(30)必输，取值：“ICBC_PERBANK_B2C”接口版本号interfaceVersionMAX(15)必输，取值：“1.0.0.3”交易数据tranData无限制必输，签名；整合所有交易数据形成的xml明文串，并做BASE64编码；具体格式定义见下文；注意：需有xml头属性；整个字段使用BASE64编码；xml明文中没有回车换行和多余空格；订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg；注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串；商城证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文献后，进行BASE64编码后产生的字符串；注：1、数据中不能涉及“|”、“&”、“=”，这些字符为银行端程序保存字符；中文变量使用GBK编码。 2、从商户Post过来的数据，参数名的名称必须与上表中完全相似，名称中的字母大小写均要相似，不能进行随意更改(在form中的提交按钮中submit不能有Name属性)；此外，如果其她input 项的Name中使用了双引号，如：，则一定注旨在引号内不要涉及空格，不要写成“mer URL ”，如果拼写错误或者多了空格，将导致数据无法辨认，无法正常进行支付3、接口名称和版本号一定要和上表中相似.。4、商户提交数据中的空格将被觉得是有效字符被接受，请商户开发时注意对多余空格的控制。5、tranData交易数据的xml串需要有xml的头，即2.1.2 tranData数据定义变量名称变量命名长度定义阐明接口名称interfaceName16必输，取值：“ICBC_PERBANK_B2C”接口版本号interfaceVersionMAX(15)必输，取值：“1.0.0.3”交易日期时间orderDate=14必输，格式为：YYYYMMDDHHmmss规定在银行系统目前时间的前1小时和后12小时范畴内，否则鉴定交易时间非法。订单号orderidMAX(30)必输，客户支付后商户网站产生的一种唯一的定单号，该订单号应当在相称长的时间内不反复。工行通过订单号加订单日期来唯一确认一笔订单的反复性。订单金额amountMAX(10)必输，客户支付订单的总金额，一笔订单一种，以分为单位。不可觉得零，必需符合金额原则。支付币种curType= 3必输，用来辨别一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”商户代码merIDMAX(20)必输，唯一拟定一种商户的代码，由商户在工行开户时，由工行告知商户。商户账号merAcctMAX(19)必输，商户入账账号，只能交易时指定。（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）检查联名标志verifyJoinFlag=1必输， 取值“1”：客户支付时，网银判断该客户与否与商户联名，是则按上送金额扣帐，否则呈现未联名错误；取值“0”：不检查客户与否与商户联名，按上送金额扣帐。语言版本LanguageMAX(10)选输，默觉得中文版取值：“EN_US”为英文版；取值：“ZH_CN”或其她为中文版。注意：大小写敏感。商品编号goodsIDMAX(30)选输商品名称goodsNameMAX(60)选输商品数量goodsNumMAX(10)选输已含运费金额carriageAmtMAX(10)选输商城提示merHintMAX(120)选输备注字段1remark1MAX(100)选输 单位：字节备注字段2remark2MAX(100)选输 单位：字节返回商户URLmerURLMAX(1024)必输必须合法的URL，交易结束，将客户引导到商户的此url，即通过客户浏览器post交易成果信息到商户的此URL返回商户变量merVARMAX(1024)选输商户自定义，当返回银行成果时，作为一种隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完毕后提交告知成果时是明文传播，建议商户对此变量使用额外安全防备措施，如签名、base642.1.3 tranData格式定义tranData格式(xml格式固定，选输字段的取值可觉得空，标签需保存)2.1.4 表单样例表单数据：tranData相应的xml明文：ICBC_PERBANK_B2C1.0.0.3-200010200EC08751300ZH_CN001威尼熊220请保存包装http:/localhost:9081/Newb2c_Pay_Mer.jsptest2.2 告知接口2.2.1 告知接口表单定义变量名称变量命名长度定义阐明返回商户变量merVAR无限制取值：商户提交接口中merVAR字段当返回银行成果时，作为一种隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完毕后提交告知成果时是明文传播，建议商户对此变量使用额外安全防备措施，如签名、base64，银行端将此字段原样返回告知成果数据notifyData无限制银行告知消息，xml格式定义见下文，提交商户时对xml明文串进行了base64编码；xml串中没有回车换行和多余空格；涉及xml头属性，且格式固定；银行对告知成果的签名数据signMsg无限制银行使用自己证书对商户告知消息notifyData字段的xml格式明文串进行的签名，然后进行BASE64编码后的字符串。注意：签名是对notifyData的xml明文进行签名，不是其BASE64编码后的串；签名后得到二进制数据，对此数据进行BASE64编码得到signMsg2.2.2 notifyData数据定义变量名称变量命名长度定义阐明接口名称interfaceName16取值：“ICBC_PERBANK_B2C”接口版本号interfaceVersionMAX(15)取值：“1.0.0.3”交易日期时间orderDate=14格式为：YYYYMMDDHHmmss规定在银行系统目前时间的前1小时和后12小时范畴内，否则鉴定交易时间非法。订单号orderidMAX(30)客户支付后商户网站产生的一种唯一的定单号，该订单号应当在相称长的时间内不反复。工行通过订单号加订单日期来唯一确认一笔订单的反复性。订单金额amountMAX(10)客户支付订单的总金额，一笔订单一种，以分为单位。不可觉得零，必需符合金额原则。支付币种curType= 3用来辨别一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”商户代码merIDMAX(20)唯一拟定一种商户的代码，由商户在工行开户时，由工行告知商户。商户账号merAcctMAX(19)商户收费入账账号 （只能交易时指定）。检查联名标志verifyJoinFlag=1取值“1”：客户支付时，网银判断该客户与否与商户联名，是则按上送金额扣帐，否则呈现未联名错误；取值“0”：不检查客户与否与商户联名，按上送金额扣帐。客户联名标志JoinFlag=1客户在银行端与否与商城联名标志位。1客户联名 0客户未联名联名会员号UserNumMAX(40)联名客户在商户的会员号。银行指令序号TranSerialNoMAX(30)银行端指令流水号返回告知日期时间notifyDateMAX(14)格式为：YYYYMMDDHHmmss订单解决状态tranStat=11-“交易成功，已清算”；2-“交易失败”；3-“交易可疑”错误描述commentMAX(100)错误描述2.2.3 notifyData格式定义notifyData格式(xml格式固定，选输字段的取值可觉得空，标签需保存)2.2.4 表单样例表单数据：notifyData相应的明文：ICBC_PERBANK_B2C1.0.0.3-200010200EC087513001交易成功！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:/银行地址/servlet/ICBCINBSEBusinessServlet”，银行来解决B2C指令的资金支付；接受告知：交易解决后，会将客户定向回商户网站，此时涉及交易成果信息和银行签名。商户接受到银行告知后，需使用开发API和银行公钥来验证银行签名，以保证告知消息的有效性，如下简要阐明验证环节：1、 获得各字段取值后，注意提交的明文需要进行base64解码才干获得。使用商户开发API和银行公钥文献对表单中的银行签名signMsg进行验签；2、 验签成功后，为保证数据一致，建议商户比较一下告知消息中订单金额、卖家卡号等核心信息和自己记录的与否一致；3、 商户根据交易成果tranStat来更新自己的指令状态和有关数据库信息；