B2C 支付接口v1.0.0.6中国工商银行软件开发中心 Copyright Reserved商户手册目录第1 章业务说明 (3)第2 章商户接口 (4)2.1支付接口 (4)2.1.1支付接口表单定义 (4)2.1.2tranData数据定义 (5)2.1.3tranData格式定义 (7)2.1.4表单样例 (8)2.2通知接口 (9)2.2.1通知接口表单定义 (9)2.2.2notifyData数据定义 (10)2.2.3notifyData格式定义 (11)2.2.4表单样例 (12)2.3商户判断支付结果及返回商户取货 (13)2.4其他说明 (13)第3 章安全API说明 (14)第4 章开发步骤 (14)4.1通用步骤 (14)4.2移动生活商户改造方法 (15)4.3附件 (16)B2C在线支付接口版本说明：1.0.0.0（基本支付）1.0.0.1（支持商户主动分期付款模式，商户不分期的情况下支持客户自助分期，商户客户都不分期的情况下，流程同1.0.0.0）1.0.0.3（1.0.0.1版本基础上，支持后台自动给商户发送支付结果通知消息，通知消息发送方式为只有支付成功的情况下发送通知，其余情况不通知）1.0.0.4（1.0.0.3版本基础上，支持他人代付功能）1.0.0.6（基于1.0.0.3版本，支持启动工行手机银行客户端（iPhone、Android）进行支付，支持工行移动生活商户进行支付，支持HTML网页版本（只支持iPhone、Android的webkit核心浏览器，需要商户侧自行判断客户的浏览器是否可用）进行支付。
注：1.0.0.6接口的HTML网页版本暂未开放！以下简述处理流程：1.客户在商户WAP网站、商户客户端（iPhone、Andrid）、工行移动生活商户浏览商品信息，签订订单；2.商户按照工行手机银行B2C支付1.0.0.6接口形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接收商户订单信息的servlet；3.客户确认使用工行支付后，提交此表单到工行；4.工行手机银行系统接收此笔订单，对订单信息和商户信息进行检查；5.通过检查则根据商户上送的启动类型，启动工行手机银行客户端程序（iPhone、Android）的支付页面或HTML网页版本（只支持iPhone、Android的webkit核心浏览器）的支付页面；6.客户输入后提交；7.银行查询客户相关信息；8.返回客户在银行的预留信息；9.客户确认；10.返回交易确认页面；11.不同类型客户使用各自认证方式进行交易确认，支持静态支付密码、动态口令卡、工银电子密码器、音频U盾（U盾只支持iPhone客户端版本）。
12.银行校验后进行支付处理；13.工行将处理结果使用http协议post方式，将通知消息数据提交到商户网站；14.给客户展现成功支付页面。
1）若商户启动类型为客户端版本，则结果页面只提供返回手机银行按钮，点击后返回手机银行程序，客户需要自行回到商户页面或商户程序进行取货，商户根据上一步的通知消息判断是否支付成功。
2）若商户启动类型为工行移动生活版本，则结果页面提供返回商户按钮，点击返回后会回到商户的页面，客户可以在此页面进行取货，商户可以根据上一步发送的通知消息判断是否支付成功。
3）若商户启动类型为HTML网页版本，则上一步通知商户时，商户返回取货地址（必须是正确格式的URL地址），银行会在成功支付页面展现取货地址链接，客户点击链接返回商户的取货地址页面。
接口定义通过接口名称和接口版本号来标识，以便将来的扩展；2.1支付接口2.1.1支付接口表单定义WAP银行B2C接口的交易数据整合到一个xml格式串，作为表单的一项整体提交； FORM 表单数据如下：变量名称变量命名长度定义说明接口名称interfaceName MAX(30) 必输，取值：“ICBC_WAPB_B2C”接口版本号interfaceVersion MAX(15) 必输，取值：“1.0.0.6”交易数据tranData 无限制必输，签名；整合所有交易数据形成的xml明文串，并做BASE64编码；具体格式定义见下文；注意：需有xml头属性；整个字段使用BASE64编码；xml明文中没有回车换行和多余空格；订单签名数据merSignMsg 无限制必输，商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg；注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串；商城证书公钥merCert 无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串；启动类型clientType MAX(2) 必输，取值：1：工行iPhone客户端版2：工行Android客户端版21：工行移动生活版（iPhone）22：工行移动生活版（Android）0：HTML版（只支持iPhone、Android的webkit核心浏览器）暂未开放注：1、数据中不能包含“|”、“&”、“=”，这些字符为银行端程序保留字符；中文变量使用GBK 编码。
2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮<input type=”submit”……>中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：<input type=text name=" merCert " value="xxxxxxx">，则一定注意在引号内不要包含空格，不要写成“mer URL ”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付3、接口名称和版本号一定要和上表中相同.。
4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。
5、tranData交易数据的xml串需要有xml的头，即<?xml version="1.0" encoding="GBK" standalone="no"?>2.1.2t ranData数据定义变量名称变量命名长度定义说明接口名称interfaceName ＝13 必输，取值：“ICBC_WAPB_B2C”接口版本号interfaceVersion=7必输，取值：“1.0.0.6”交易日期时间orderDate =14 必输，格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。
订单号orderid MAX(30) 必输，客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。
工行通过订单号加订单日期来唯一确认一笔订单的重复性。
订单金额amount MAX(10) 必输，客户支付订单的总金额，一笔订单一个，以分为单位。
不可以为零，必需符合金额标准。
分期付款期数installmentTimesMAX（2）必输，每笔订单一个；取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上述值，否则订单校验不通过。
支付币种curType = 3 必输，用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。
取值：“001”商户代码merID MAX(20) 必输，唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
商户账号merAcct MAX(19) 必输，商户入账账号，只能交易时指定。
（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）联名校验标志verifyJoinFlag =1 必输，手机银行订单必输0，不校验语言版本Language MAX(10) 选输，默认为中文版目前只支持中文版取值：“zh_CN”或其他为中文版。
注意：大小写敏感。
商品编号goodsID MAX(10) 选输商品名称goodsName MAX(40) 选输商品数量goodsNum MAX(10) 选输已含运费金额carriageAmt MAX(10) 选输商城提示merHint MAX(40) 选输备注字段1 remark1 MAX(100) 选输如果希望对订单的有效日期进行限定，此项必须输入类似”20110802152230”的时间串代表8月2日15:22:30之前支付订单有效。
若不需要限定，此项送空，送其他值不合法。
备注字段2 remark2 MAX(100) 选输通知商户URL merURL MAX(1024) 必输必须合法的URL，交易结束，银行使用HTTP协议POST方式向此地址发送通知信息；目前只支持80端口。
返回商户变量merVAR MAX(1024) 选输商户自定义，当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。
由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64通知类型notifyType =2 必输在交易转账处理完成后把交易结果通知商户的处理模式。
取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段；取值“AG”：在交易完成后不通知商户。
商户需使用浏览器登录工行的B2C商户服务网站，或者使用工行提供的客户端程序API主动获取通知信息。
结果发送类型resultType =1 选输取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1”，银行只向商户发送交易成功的通知信息。
只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。
备用字段1 backup1 100 不输，预留字段备用字段2 backup2 100 不输，预留字段备用字段3 backup3 100 不输，预留字段备用字段4 backup4 100 不输，预留字段2.1.3t ranData格式定义tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)<?xml version="1.0" encoding="GBK" standalone="no"?><B2CReq><interfaceName></interfaceName><interfaceVersion></interfaceVersion><orderInfo><orderDate></orderDate><orderid></orderid><amount></amount><installmentTimes></installmentTimes><curType></curType><merID></merID><merAcct></merAcct></orderInfo><custom><verifyJoinFlag></verifyJoinFlag><Language></Language></custom><message><goodsID></goodsID><goodsName></goodsName><goodsNum></goodsNum><carriageAmt></carriageAmt><merHint></merHint><remark1></remark1><remark2></remark2><merURL></merURL><merVAR></merVAR><notifyType></notifyType><resultType></resultType><backup1></backup1><backup2></backup2><backup3></backup3><backup4></backup4></message></B2CReq>2.1.4表单样例表单数据：<INPUT NAME="interfaceName" TYPE="text" value="ICBC_WAPB_B2C"><INPUT NAME="interfaceVersion" TYPE="text" value="1.0.0.6"><INPUT NAME="clientType" TYPE="text" value="1"><INPUT NAME="tranData" TYPE="text" value="PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iR 0JLIiBzdGFuZGFsb25lPSJubyI/PjxCMkNSZXE+PGludGVyZmFjZU5hbWU+SUNCQ19XQVBCX0IyQzwvaW50 ZXJmYWNlTmFtZT48aW50ZXJmYWNlVmVyc2lvbj4xLjAuMC42PC9pbnRlcmZhY2VWZXJzaW9uPjxvcmRlckl uZm8+PG9yZGVyRGF0ZT4yMDEzMDQxMDExMzUyNTwvb3JkZXJEYXRlPjxvcmRlcmlkPjIwMTMwNDEwMTEzNT I1MDwvb3JkZXJpZD48YW1vdW50PjUwMDwvYW1vdW50PjxpbnN0YWxsbWVudFRpbWVzPjE8L2luc3RhbGxtZ W50VGltZXM+PGN1clR5cGU+MDAxPC9jdXJUeXBlPjxtZXJJRD4wMjAwRUMyMzMzNTE0OTwvbWVySUQ+PG1l ckFjY3Q+MDIwMDAyNDEwOTAzMTU0ODU2OTwvbWVyQWNjdD48L29yZGVySW5mbz48Y3VzdG9tPjx2ZXJpZnl Kb2luRmxhZz4wPC92ZXJpZnlKb2luRmxhZz48TGFuZ3VhZ2U+emhfQ048L0xhbmd1YWdlPjwvY3VzdG9tPj xtZXNzYWdlPjxnb29kc0lEPjAwMTwvZ29vZHNJRD48Z29vZHNOYW1lPrPk1rW/qDwvZ29vZHNOYW1lPjxnb 29kc051bT4yPC9nb29kc051bT48Y2FycmlhZ2VBbXQ+MTAwMDwvY2FycmlhZ2VBbXQ+PG1lckhpbnQ+uMPJ zMa3sru7u7K7zcs8L21lckhpbnQ+PHJlbWFyazE+PC9yZW1hcmsxPjxyZW1hcmsyPjwvcmVtYXJrMj48bWV yVVJMPmh0dHA6Ly84Mi4yMDAuNDYuMTMwL2VtdWxhdG9yL1dhcF9zaG9wX3Jlc3VsdC5qc3A8L21lclVSTD 48bWVyVkFSPjwvbWVyVkFSPjxub3RpZnlUeXBlPkhTPC9ub3RpZnlUeXBlPjxyZXN1bHRUeXBlPjE8L3Jlc3VsdFR5cGU+PGJhY2t1cDE+PC9iYWNrdXAxPjxiYWNrdXAyPjwvYmFja3VwMj48YmFja3VwMz48L2JhY2t1 cDM+PGJhY2t1cDQ+PC9iYWNrdXA0PjwvbWVzc2FnZT48L0IyQ1JlcT4="><INPUT NAME="merSignMsg" TYPE="text" value="k7dt7Hj4FhILgX5JmqOqWOxJ5L93w6mnem6LZvm HfhN4xXBwoRYJ/bQmInTH5L3mAnZgLGtRlF5Ml+HXTF0sWqrev2zB5DPhqFSyi9d0JbhSXQN3w+n5XS8paU Q6z8hl3fA2RssvdllbHBpfe/GelU/HWmm8k6VquvNnw0af50E="><INPUT NAME="merCert" TYPE="text" value="MIIChjCCAe+gAwIBAgIKbaHKEE0tAAAH3zANBgkqhk iG9w0BAQUFADA2MRkwFwYDVQQDExBjb3JiYW5rNDMgc2RjIENOMRkwFwYDVQQKExBjb3JiYW5rNDMuY29tL mNuMB4XDTE1MTEzMDAyMzczMloXDTE2MTEzMDAyMzczMlowPzETMBEGA1UEAxMKQjJDLmUuMDIwMDENMAsG A1UECxMEMDIwMDEZMBcGA1UEChMQY29yYmFuazQzLmNvbS5jbjCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYk CgYEAwV4bOl8ByDx1So1smhCWvzCegIVze5T6qreQyUiBYI6B5hnkd6ke3ToxFUDRawdN8JWAGW+0Ze02ir fg4cnZs3f8PHZ5IEiLYOGrHUWfEsk3QhKrSCLyyzIACeceNMVlIcjzYtemziNej5NZsv787WQSpY5gy+2vN UDt+f/Hj6ECAwEAAaOBkTCBjjAfBgNVHSMEGDAWgBS+7/FOAOQ4De97QGDOvMygCG34YzBMBgNVHR8ERTBD MEGgP6A9pDswOTENMAsGA1UEAxMEY3JsMzENMAsGA1UECxMEY2NybDEZMBcGA1UEChMQY29yYmFuazQzLmN vbS5jbjAdBgNVHQ4EFgQUfTKD6Q/uHEN8zthhoVr3/KCJiQcwDQYJKoZIhvcNAQEFBQADgYEALHBcTTjXI5 fgd/b60y8ObhxMGWiDDpb2f9gMoKYmkGhFCf2+KGSBpPuYc9u3J8P0CUQ9znyYpxSGXKzVHh34PYxvGLpCQ Z/liSKsfgD/JXvNqwgBmMXq0MzoMrYc6JMaMvSmfy/jVq9D6YFM5AnzsKLG+FQPckNx6O7pRqNzL1E=">tranData对应的xml明文：<?xml version="1.0" encoding="GBK"standalone="no"?><B2CReq><interfaceName>ICBC_WAPB_B2C</interfaceName><interfaceVers ion>1.0.0.6</interfaceVersion><orderInfo><orderDate>20130410121036</orderDate><orde rid>201304101210360</orderid><amount>500</amount><installmentTimes>1</installmentTi mes><curType>001</curType><merID>0200EC23335149</merID><merAcct>0200024109031548569 </merAcct></orderInfo><custom><verifyJoinFlag>0</verifyJoinFlag><Language>zh_CN</La nguage></custom><message><goodsID>001</goodsID><goodsName>充值卡</goodsName><goodsNum>2</goodsNum><carriageAmt>1000</carriageAmt><merHint>该商品不换不退</merHint><remark1></remark1><remark2></remark2><merURL>http://82.200.46.130/emulat or/Wap_shop_result.jsp</merURL><merVAR></merVAR><notifyType>HS</notifyType><resultT ype>1</resultType><backup1></backup1><backup2></backup2><backup3></backup3><backup4 ></backup4></message></B2CReq>2.2通知接口2.2.1通知接口表单定义变量名称变量命名长度定义说明返回商户变量merVAR无限制取值：商户提交接口中merVAR字段当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。