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

网上银行商户手册B2C支付接口v1.0.0.3中国工商银行软件开发中心CopyrightReserved商户手册网上银行商户手册第2页共13页目录第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网上银行商户手册第3页共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、商户使用API证书对订单签名并返回客户端3、客户将订单数据提交银行4、校验商户签名和证书、订单数据、商户状态等5、返回客户支付页面回显订单指定卡号或提示客户输入卡号6、客户确定提交8、返回预留信息7、检查客户信息9、客户确认10、返回确认页面11、客户确认（静态密码、动态密码、签名）主机12、发主机指令13、返回客户支付结果14、将结果返回商户网上银行商户手册第4页共13页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通知的方式称为原模式接口；网上银行商户手册第5页共13页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中的提交按钮inputtype=”submit”……中submit不能有Name属性)；此外，如果其他input项的Name中使用了双引号，如：inputtype=text网上银行商户手册第6页共13页name=merCertvalue=xxxxxxx，则一定注意在引号内不要包含空格，不要写成“merURL”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付3、接口名称和版本号一定要和上表中相同.。4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。5、tranData交易数据的xml串需要有xml的头，即?xmlversion=1.0encoding=GBKstandalone=no?2.1.2tranData数据定义变量名称变量命名长度定义说明接口名称interfaceName＝16必输，取值：“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)必输，商户入账账号，只能交易时指定。（商户付给银行手续费的账户，可