中国工商银行网上银行网上支付接口规范共23页文档.docx
《中国工商银行网上银行网上支付接口规范共23页文档.docx》由会员分享，可在线阅读，更多相关《中国工商银行网上银行网上支付接口规范共23页文档.docx（17页珍藏版）》请在冰豆网上搜索。
中国工商银行网上银行网上支付接口规范共23页文档
B2C支付接口v1.0.0.3
商户手册
中国工商银行软件开发中心
CopyrightReserved
第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表单数据如下：
变量名称
变量命名
长度定义
说明
接口名称
interfaceName
MAX（30）
必输，
取值：
“ICBC_PERBANK_B2C”
接口版本号
interfaceVersion
MAX（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中使用了双引号，如：
，则一定注意在引号内不要包含空格，不要写成“merURL”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付
3、接口名称和版本号一定要和上表中相同.。
4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。
5、tranData交易数据的xml串需要有xml的头，即
xmlversion="1.0"encoding="GBK"standalone="no"?
>
2.1.2tranData数据定义
变量名称
变量命名
长度定义
说明
接口名称
interfaceName
＝16
必输，
取值：
“ICBC_PERBANK_B2C”
接口版本号
interfaceVersion
MAX（15）
必输，
取值：
“1.0.0.3”
交易日期时间
orderDate
=14
必输，
格式为：
YYYYMMDDHHmmss
要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。
订单号
orderid
MAX（30）
必输，
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。
工行通过订单号加订单日期来唯一确认一笔订单的重复性。
订单金额
amount
MAX（10）
必输，
客户支付订单的总金额，一笔订单一个，以分为单位。
不可以为零，必需符合金额标准。
支付币种
curType
=3
必输，
用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。
取值：
“001”
商户代码
merID
MAX（20）
必输，
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
商户账号
merAcct
MAX（19）
必输，
商户入账账号，只能交易时指定。
（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）
检验联名标志
verifyJoinFlag
=1
必输，
取值“1”：
客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；
取值“0”：
不检验客户是否与商户联名，按上送金额扣帐。
语言版本
Language
MAX（10）
选输，默认为中文版
取值：
“EN_US”为英文版；
取值：
“ZH_CN”或其他为中文版。
注意：
大小写敏感。
商品编号
goodsID
MAX（30）
选输
商品名称
goodsName
MAX（60）
选输
商品数量
goodsNum
MAX（10）
选输
已含运费金额
carriageAmt
MAX（10）
选输
商城提示
merHint
MAX（120）
选输
备注字段1
remark1
MAX（100）
选输单位：
字节
备注字段2
remark2
MAX（100）
选输单位：
字节
返回商户URL
merURL
MAX（1024）
必输
必须合法的URL，交易结束，将客户引导到商户的此url，即通过客户浏览器post交易结果信息到商户的此URL
返回商户变量
merVAR
MAX（1024）
选输
商户自定义，当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。
由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64
2.1.3tranData格式定义
tranData格式（xml格式固定，选输字段的取值可以为空，标签需保留）
xmlversion="1.0"encoding="GBK"standalone="no"?
>
2.1.4表单样例
表单数据：
升级会员 