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

《中国工商银行网上银行新B2C在线支付接口说明V10011.doc》由会员分享，可在线阅读，更多相关《中国工商银行网上银行新B2C在线支付接口说明V10011.doc（16页珍藏版）》请在三一办公上搜索。

1、 B2C支付接口v1.0.0.11商户手册中国工商银行软件开发中心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 章 业务说明以下简述处理流程：1. 客户在商户网站浏览商品信息，签订订单；2. 商户按照工行B2

2、C支付1.0.0.11接口形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接收商户订单信息的servlet；3. 客户确认使用工行支付后，提交此表单到工行；4. 工行网银系统接收此笔订单，对订单信息和商户信息进行检查；5. 通过检查则显示工行支付页面，1.0.0.11版本会提示客户输入交易卡号；6. 客户输入后提交；7. 银行查询客户相关信息；8. 返回客户在银行的预留信息；9. 客户确认；10. 返回交易确认页面；11. 不同类型客户使用各自认证方式进行交易确认，支持静态支付密码、动态口令卡、证书签名；12. 银行校验后

3、进行支付处理；13. 工行进行支付指令处理后，如果商户需要工行实时通知，则工行将处理结果使用http协议post方式将通知消息数据提交到商户网站（这个接收银行通知消息的商户端地址是随商户订单数据提交银行的merURL字段），商户返回取货地址或关闭这个银行与其建立的连接后，银行才显示交易结果页面给客户。（注意1、发送通知和显示结果页面是串行的，所以商户端接收银行通知处理时间太长可能导致客户等待超时，造成银行不能将交易结果页面显示给客户。2、此连接是银行服务器自动和商户进行的连接，商户返回也是直接返回给银行，商户端不能对银行的这个请求进行重定向。）14. 工行进行支付指令处理后，如果商户不需要工行

4、实时通知，则工行直接显示交易结果给客户。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，在原有接口基础上扩展支持红利卡，支持红利卡的商户采用；当上送项不支持

5、红利卡的时候，接口等同于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，在原有接口基础上增

6、加1.0.0.8的透支标志控制，增加商户上送数据,丰富及扩展用户体验，增加校验商户域名，同1.0.0.0通知方式）第 2 章 商户接口2.1 支付接口2.1.1 支付接口表单定义新模式接口的交易数据整合到一个xml格式串，作为表单的一项整体提交，不再同原来每个字段都是key-value形式；FORM表单数据如下：变量名称变量命名长度定义说明接口名称interfaceNameMAX(30)必输，取值：“ICBC_PERBANK_B2C”接口版本号interfaceVersionMAX(15)必输，取值：“1.0.0.11”交易数据tranData无限制必输，签名；整合所有交易数据形成的xml明文

7、串，并做BASE64编码；具体格式定义见下文；注意：需有xml头属性；整个字段使用BASE64编码；xml明文中没有回车换行和多余空格；订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg；注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串；商城证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串；注：1、数据中不能包含“|”、“&”、“=”，这些字符

8、为银行端程序保留字符；中文变量使用GBK编码。 2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：，则一定注意在引号内不要包含空格，不要写成“mer URL ”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付3、接口名称和版本号一定要和上表中相同.。4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。5、tranData交易数据的xml串需要有xml的头，即2.1.2 tr

9、anData数据定义变量名称变量命名长度定义说明接口名称interfaceName16必输，取值：“ICBC_PERBANK_B2C”接口版本号interfaceVersionMAX(15)必输，取值：“1.0.0.11”交易日期时间orderDate=14必输，格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。订单号orderidMAX(30)必输，每笔订单都需要有不同的订单号；客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。订单金额amountMAX

10、(10)必输，每笔订单一个；客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。分期付款期数installmentTimesMAX（2）必输，每笔订单一个；取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。商户账号merAcctMAX(19)必输，每笔订单一个，可以相同；商户入账账号，只能交易时指定。（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）商品编号goodsIDMAX(30)选输，每笔订单一个；商品名称goodsNameMAX(60)必输，每笔订单一个；商品数量g

11、oodsNumMAX(10)选输，每笔订单一个；已含运费金额carriageAmtMAX(10)选输，每笔订单一个；检验联名标志verifyJoinFlag=1必输， 取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。语言版本LanguageMAX(10)选输，默认为中文版取值：“EN_US”为英文版；取值：“ZH_CN”或其他为中文版。注意：大小写敏感。支付币种curType= 3必输，用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”商户代码merIDMAX(2

12、0)必输，唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。支持订单支付的银行卡种类creditType= 1必输默认“2”。取值范围为0、1、2，其中0表示仅允许使用借记卡支付，1表示仅允许使用信用卡支付，2表示借记卡和信用卡都能对订单进行支付通知类型notifyType= 2必输在交易转账处理完成后把交易结果通知商户的处理模式。取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段；取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的B2C商户服务网站，或者

13、使用工行提供的客户端程序API主动获取通知信息。结果发送类型resultType=1选输取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1”，银行只向商户发送交易成功的通知信息。只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。商户referencemerReferenceMAX(200)选输，上送商户网站域名，如果上送，工行会在客户支付订单时，校验商户上送域名与客户跳转工行支付页面之前网站域名的一致性。客户端IPmerCustomIpMAX(20)选输，工行在支付页面显示该信息。虚拟商品/实物商品标志位goodsType

14、=1必输取值“0”：虚拟商品；取值“1”，实物商品。买家用户号merCustomIDMAX(100)选输买家联系电话merCustomPhoneMAX(20)选输，当商户上送goodsType值为“0”，该项必输收货地址goodsAddressMAX(200)选输，当商户上送goodsType值为“1”，该项必输订单备注merOrderRemarkMAX(200)选输，工行在支付页面显示该信息。商城提示merHintMAX(120)选输备注字段1remark1MAX(100)选输 单位：字节备注字段2remark2MAX(100)选输 单位：字节返回商户URLmerURLMAX(1024)必输

15、必须合法的URL，交易结束，将客户引导到商户的此url，即通过客户浏览器post交易结果信息到商户的此URL返回商户变量merVARMAX(1024)选输商户自定义，当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64注：红色字体部分内容，每笔订单都有一份。2.1.3 tranData格式定义tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)ICBC_PERBANK_B2C1.0.0.11201003081416290010200EC20

16、001119201003081416290110200026009018372212001威尼熊220201003081416291110200026009018372212001威尼熊2200ZH_CN2AG1localhost127.0.0.1112345613466780886三里屯防欺诈接口专用请保留包装http:/localhost:9080/EbizSimulate/emulator/Newb2c_Pay_Mer.jsptest注：红色字体部分，即是循环部分，最大5次，超过则接口校验报错。2.1.4 表单样例表单数据：tranData对应的xml明文：ICBC_PERBANK_B2

17、C1.0.0.11201003081416290010200EC20001119201003081416290110200026009018372212001威尼熊220201003081416291110200026009018372212001威尼熊2200ZH_CN2AG1localhost127.0.0.1112345613466780886三里屯防欺诈接口专用请保留包装http:/localhost:9080/EbizSimulate/emulator/Newb2c_Pay_Mer.jsptest2.2 通知接口2.2.1 通知接口表单定义变量名称变量命名长度定义说明返回商户变量me

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

19、E64编码后的字符串。注意：签名是对notifyData的xml明文进行签名，不是其BASE64编码后的串；签名后得到二进制数据，对此数据进行BASE64编码得到signMsg2.2.2 notifyData数据定义变量名称变量命名长度定义说明接口名称interfaceName16取值：“ICBC_PERBANK_B2C”接口版本号interfaceVersionMAX(15)取值：“1.0.0.11”交易日期时间orderDate=14格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。订单号orderidMAX(30)客户支付后商户

20、网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。订单金额amountMAX(10)客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。分期付款期数installmentTimesMAX（2）必输，每笔订单一个；取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。商户账号merAcctMAX(19)商户收费入账账号 （只能交易时指定）。支付币种curType= 3用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”商户代码merIDM

21、AX(20)唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。检验联名标志verifyJoinFlag=1取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。客户联名标志JoinFlag=1客户在银行端是否与商城联名标志位。1客户联名 0客户未联名联名会员号UserNumMAX(40)联名客户在商户的会员号。银行指令序号TranSerialNoMAX(30)银行端指令流水号批次号TranBatchNoMAX(15)银行端为多笔一次提交的指令生成一个唯一的批次号返回通知日期时间notifyD

22、ateMAX(14)格式为：YYYYMMDDHHmmss订单处理状态tranStat=11-“交易成功，已清算”；2-“交易失败”；3-“交易可疑”错误描述commentMAX(100)错误描述注：红色字体部分内容，每笔订单都有一份。2.2.3 notifyData格式定义notifyData格式(xml格式固定，选输字段的取值可以为空，标签需保留)注：红色字体部分，即是循环部分，最大5次，根据商户上送的数量返回。2.2.4 表单样例表单数据：INPUT TYPE=hidden NAME=signMsg VALUE=UYE6nBdgkaV1uxZPzyIG5BYZmVvDl29tIvmp4XxWBsVxsw+yNwi86p