手机银行(WAP)B2C在线支付接口说明V1.0.0.6

手机银行商户手册

B2C支付接口v1.0.0.6

中国工商银行软件开发中心 Copyright Reserved

商户手册 手机银行商户手册

目录

第 1 章 业务说明 ....................................................................................................................... 3 第 2 章 商户接口 ....................................................................................................................... 4

2.1 支付接口 ....................................................................................................................... 4 2.1.1 支付接口表单定义 ................................................................................................... 4 2.1.2 tranData数据定义 .................................................................................................. 5 2.1.3 tranData格式定义 .................................................................................................. 7 2.1.4 表单样例 ................................................................................................................... 8 2.2 通知接口 ....................................................................................................................... 9 2.2.1 通知接口表单定义 ................................................................................................... 9 2.2.2 notifyData数据定义 ............................................................................................ 10 2.2.3 notifyData格式定义 ............................................................................................ 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

第 2 页 共 17 页

手机银行商户手册

第 1 章 业务说明

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地址），银行会在成功支付页面展现取货地址链接，客户点击链接返回商户的取货地址页面。

第 3 页 共 17 页

手机银行商户手册

第 2 章 商户接口

接口定义通过接口名称和接口版本号来标识，以便将来的扩展；

2.1 支付接口

2.1.1 支付接口表单定义

WAP银行B2C接口的交易数据整合到一个xml格式串，作为表单的一项整体提交； FORM

表单数据如下： 变量名称 接口名称 接口版本号 变量命名 interfaceName interfaceVersion 长度定义 MAX(30) MAX(15) 必输， 取值：“ICBC_WAPB_B2C” 必输， 取值：“1.0.0.6” 必输，签名； 整合所有交易数据形成的xml明文串，并做BASE64编码； 交易数据 tranData 无限制 具体格式定义见下文； 注意： 需有xml头属性；整个字段使用BASE64编码； xml明文中没有回车换行和多余空格； 必输， 商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，订单签名数据 merSignMsg 无限制 得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg； 注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串； 商城证书公钥 必输， merCert 无限制 商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串； 必输， 取值： 1：工行iPhone客户端版 启动类型 clientType MAX(2) 2：工行Android客户端版 21：工行移动生活版（iPhone） 22：工行移动生活版（Android） 0：HTML版（只支持iPhone、Android第 4 页 共 17 页

说明 手机银行商户手册

的webkit核心浏览器）暂未开放

注：

1、数据中不能包含“|”、“&”、“=”，这些字符为银行端程序保留字符；中文变量使用GBK编码。

2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：

4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。 5、tranData交易数据的xml串需要有xml的头，即

2.1.2 tranData数据定义

变量名称 接口名称 接口版本号 变量命名 interfaceName interfaceVersion 长度定义 ＝13 =7 必输， 取值：“ICBC_WAPB_B2C” 必输， 取值：“1.0.0.6” 必输， 格式为：YYYYMMDDHHmmss 交易日期时间 orderDate =14 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。 必输， 客户支付后商户网站产生的一个唯一订单号 orderid MAX(30) 的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。 必输， 订单金额 amount MAX(10) 客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。 必输，每笔订单一个； 分期付款期数 installmentTimes curType MAX（2） 取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上述值，否则订单校验不通过。 支付币种 = 3 必输， 第 5 页 共 17 页 说明

手机银行商户手册

用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。 取值： “001” 必输， 商户代码 merID MAX(20) 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。 必输， 商户入账账号，只能交易时指定。（商商户账号 merAcct MAX(19) 户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号） 联名校验标志 verifyJoinFlag =1 必输， 手机银行订单必输0，不校验 选输，默认为中文版 语言版本 Language MAX(10) 目前只支持中文版 取值：“zh_CN”或其他为中文版。 注意：大小写敏感。 商品编号 商品名称 商品数量 已含运费金额 商城提示 goodsID goodsName goodsNum carriageAmt merHint MAX(10) MAX(40) MAX(10) MAX(10) 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 在交易转账处理完成后把交易结果通知商户的处理模式。 第 6 页 共 17 页

手机银行商户手册

取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段； 取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的B2C商户服务网站，或者使用工行提供的客户端程序API主动获取通知信息。 选输 取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息； 结果发送类型 resultType =1 取值“1”，银行只向商户发送交易成功的通知信息。 只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。 备用字段1 备用字段2 备用字段3 备用字段4 backup1 backup2 backup3 backup4 100 100 100 100 不输，预留字段 不输，预留字段 不输，预留字段 不输，预留字段 2.1.3 tranData格式定义

tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)

第 7 页 共 17 页

手机银行商户手册

2.1.4 表单样例

表单数据：

第 8 页 共 17 页

手机银行商户手册

3VsdFR5cGU+PGJhY2t1cDE+PC9iYWNrdXAxPjxiYWNrdXAyPjwvYmFja3VwMj48YmFja3VwMz48L2JhY2t1cDM+PGJhY2t1cDQ+PC9iYWNrdXA0PjwvbWVzc2FnZT48L0IyQ1JlcT4=\

standalone=\ion>1.0.0.62013041012103620130410121036050010010200EC2333514902000241090315485690zh_CN001充值卡

21000该商品不换不退

http://82.200.46.130/emulator/Wap_shop_result.jspHS1

2.2 通知接口

2.2.1 通知接口表单定义

变量名称 返回商户变量 变量命名 merVAR 长度定义 无限制 说明 取值：商户提交接口中merVAR字段当第 9 页 共 17 页

手机银行商户手册

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

2.2.2 notifyData数据定义

变量名称 接口名称 接口版本号 变量命名 interfaceName interfaceVersion 长度定义 ＝13 MAX(15) 说明 取值：“ICBC_WAPB_B2C” 取值：“1.0.0.6” 格式为：YYYYMMDDHHmmss 交易日期时间 orderDate =14 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。 客户支付后商户网站产生的一个唯一订单号 orderid MAX(30) 的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。 订单金额 分期付款期数 amount installmentTimes merID merAcct MAX(10) MAX（2） 客户支付订单的总金额，以分为单位。 取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。 MAX(20) MAX(19) 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。 商户收费入账账号 （只能交易时指定）。 第 10 页 共 17 页

商户代码 商户账号

手机银行商户手册

支付币种 联名校验标志 客户是否联名标志 会员号 银行指令序号 返回通知日期时间 订单处理状态 错误描述 curType verifyJoinFlag JoinFlag UserNum TranSerialNo notifyDate =3 =1 =1 MAX(30) MAX(30) MAX(14) 取值：“001” 取值：“0” 取值：“0” 取值为空，该字段暂时无用 银行端指令流水号 格式为：YYYYMMDDHHmmss 1-“交易成功，已清算”； tranStat comment =1 MAX(100) 2-“交易失败”； 3-“交易可疑” 错误描述

2.2.3 notifyData格式定义

notifyData格式(xml格式固定，选输字段的取值可以为空，标签需保留)

第 11 页 共 17 页

手机银行商户手册

2.2.4 表单样例

表单数据：

VALUE=\Q1Jlcz48aW50ZXJmYWNlTmFtZT5JQ0JDX1dBUEJfQjJDPC9pbnRlcmZhY2VOYW1lPjxpbnRlcmZhY2VWZXJzaW9uPjEuMC4wLjY8L2ludGVyZmFjZVZlcnNpb24+PG9yZGVySW5mbz48b3JkZXJEYXRlPjIwMTMwNDEwMTMzODQ2PC9vcmRlckRhdGU+PG9yZGVyaWQ+MjAxMzA0MTAxMzM4NDYwPC9vcmRlcmlkPjxhbW91bnQ+NTAwPC9hbW91bnQ+PGluc3RhbGxtZW50VGltZXM+MTwvaW5zdGFsbG1lbnRUaW1lcz48bWVyQWNjdD4wMjAwMDI0MTA5MDMxNTQ4NTY5PC9tZXJBY2N0PjxtZXJJRD4wMjAwRUMyMzMzNTE0OTwvbWVySUQ+PGN1clR5cGU+MDAxPC9jdXJUeXBlPjx2ZXJpZnlKb2luRmxhZz4wPC92ZXJpZnlKb2luRmxhZz48Sm9pbkZsYWc+MDwvSm9pbkZsYWc+PFVzZXJOdW0+PC9Vc2VyTnVtPjwvb3JkZXJJbmZvPjxiYW5rPjxUcmFuU2VyaWFsTm8+MTIzNDU2Nzg5MDwvVHJhblNlcmlhbE5vPjxub3RpZnlEYXRlPjIwMTMwNDEwMTM0MTU0PC9ub3RpZnlEYXRlPjx0cmFuU3RhdD4xPC90cmFuU3RhdD48Y29tbWVudD69u9LXs8m5pqOs0tHH5cvjo6E8L2NvbW1lbnQ+PC9iYW5rPjwvQjJDUmVzPg==\

notifyData对应的明文：

1.0.0.620130410133846201304101338460500102000241090315485690200EC23335149001001234567890201304101341541交易成功，已清算！

第 12 页 共 17 页

手机银行商户手册

2.1 商户判断支付结果及返回商户取货

商户可以在支付接口中配置接收银行通知来实时获取支付结果，若支付接口中配置的是不接收银行通知或接收通知异常，商户还可以通过浏览器登录工行的B2C商户服务网站，或者使用工行提供的客户端程序API主动获取支付结果。

若商户选择的启动方式为客户端版本， 则客户端支付结果页面只提供返回手机银行的按钮，客户点击后只会返回手机银行客户端的登录页面或主菜单，但结果页面会提示客户自行回到商户界面进行取货。在取货页面，商户需要根据银行通知或主动获取支付结果自行判断支付是否完成，客户是否可以进行取货。

若商户选择的启动方式为移动生活商户版本，则客户端结果页面只提供返回商户按钮，客户点击此按钮会回到商户提交订单的页面。商户可以在客户提交订单时设立“已完成支付”按钮，客户完成支付流程后回到此页面点击“已完成支付”按钮，商户需要根据银行通知或主动获取支付结果自行判断支付是否完成，客户是否可以进行取货。

若商户选择的启动方式为HTML版本，则支付流程都是在客户手机的浏览器中完成的，并不会启动工行客户端程序，所以若商户希望在支付结果页面能跳转到自己的取货页面，则商户需要在支付接口中配置接收银行通知，并在接收银行通知消息后返回取货页面的URL给银行，银行将在结果页面显示链接到此地址的按钮。若商户配置不接收银行通知或返回的取货地址不正确，则在结果页面将不会提供任何按钮，客户需要自行回到商户页面取货，此时商户需要自行判断支付是否完成。

返回取货地址提示：

1、商户返回实质上只是一个内容为URL的字符串，不能有任何多余的东西，包括不能有任何的html的标签；类似以下http报文回应

HTTP/1.1 200 OK Server: Apache/1.39 Content-Length: 24 Content-type: text/html http://www.merweb.com.cn

2、此URL可以通过“?”来挂参数；举例：

http://www.merweb.com.cn/getGoods.jsp?user=guest&level=3

银行在显示给客户的交易结果页面上提供此URL的链接，客户点击此链接后，挂载的参数将以GET方式提交商户。

2.3 其他说明

1、商户可能收到的银行通知 指令成功：

只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。 指令失败：

商户可能会收到多笔客户支付失败的信息，如密码输入错误，限额超限等。 指令可疑：

第 13 页 共 17 页

手机银行商户手册

由于手机银行系统与后台业务处理系统间通讯异常，造成手机银行不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。

2、没有收到客户浏览器转发的银行通知：

由于客户浏览器端或互联网通讯等原因可能造成商户端接收不到客户浏览器提交的银行通知。当没有收到银行通知时，可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。

3、商户提交的订单信息和银行返回的通知消息都是xml串，并且进行了BASE64编码；提交和返回的xml都应有xml头；商户提交的订单xml明文，和银行发送给商户的通知消息xml明文，必须是GBK编码的。

4、其它页面不作限制，可以是其它编码，如utf-8。

第 3 章 安全API说明

为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上文的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。安全API的使用方法可参见相关开发语言的说明和demo程序；

第 4 章 开发步骤

商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。

4.1通用步骤

生成订单：

1、商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；

2、商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名） 商户进行开发，准备要求的订单数据；

第 14 页 共 17 页

手机银行商户手册

3、其中订单签名数据merSignMsg字段是对明文的签名数据；需要使用提供的API函数和商户私钥进行签名，得到签名串，然后做BASE64编码；

4、其中商城证书公钥merCert字段需要使用API函数做BASE64编码； 5、准备好订单数据，即完成订单部分的开发；

提交订单：

本B2C支付接口支持多种启动类型，需要商户侧根据需要自行判断选择

1、若商户开发的是Android、iPhone系统的客户端程序，则商户提交订单可以采用 Android平台的WebView控件或iOS平台的UIWebView控件提交表单数据到银行接收入口，订单中的启动类型可以选择客户端版本或HTML版本，若为客户端版本则会打开我行手机银行客户端进行支付，若为HTML版本则在当前WebView（UIWebView）控件或手机系统浏览器中进行支付。

2、若商户开发的是WAP商城站点，直接提交表单数据到银行接收入口即可；订单中的启动类型可以选择客户端版本或HTML版本；若启动类型为客户端版本，则需要商户自行判断客户使用的手机系统（可以通过浏览器UA判断）来选择启动Android版本或iPhone版本。若启动类型为HTML版本，则需要商户自行判断客户使用的手机系统及浏览器是否满足本接口的要求（Android、iPhone系统、Webkit核心浏览器）；

3、若商户开发的是工行合作的移动生活商户，请参考4.2节的开发步骤提交订单数据。 4、银行侧接收商户提交入口如下： 模拟测试环境：

https://mywap2.dccnet.com.cn/ICBCWAPBank/servlet/ICBCWAPEBizServlet 生产环境：

https://mywap2.icbc.com.cn/ICBCWAPBank/servlet/ICBCWAPEBizServlet

接收通知：

交易支付成功后，会将交易结果信息和银行签名发送给商户。商户接收到银行通知后，需使用开发API和银行公钥来验证银行签名，以确保通知消息的有效性，以下简要说明验证步骤：

1、获得各字段取值后，注意提交的明文需要进行base64解码才能获得。使用商户开发API和银行公钥文件对表单中的银行签名signMsg进行验签；

2、验签成功后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关键信息和自己记录的是否一致；

3、商户根据交易结果tranStat来更新自己的指令状态和相关数据库信息；

4.2移动生活商户改造方法

工行移动生活商户是指在我行iPhone、Android手机银行主屏移动生活栏目中展现的这些商户，此部分商户与我行是合作关系。目前此类商户的支付流程使用的是我行的无界面工银e支付接口。为了统一支付界面风格，建议此部分商户统一使用我行最新的B2C支付接口完成支付流程。开发步骤请先参见通用步骤，以下为特殊改造点：

1、只有最新版本的客户端程序（Android：1.0.0.9、iPhone1.0.1.1）才支持本B2C支付接口，所以商户需要使用附件js文件中的以下代码判断当前的手机银行客户端是否支持本B2C支付接口，若不支持，商户还需要使用现行的无界面工银e支付完成支付流程，若支持，商户页面需要按要求组织订单数据使用本B2C接口完成支付流程。

第 15 页 共 17 页

本文来源：https://www.bwwdw.com/article/rhv6.html