B2C支付接口v1.0.0.3
中国工商银行软件开发中心
Copyright Reserved
目录
第 1 章业务说明 (2)
第 2 章商户接口 (4)
2.1 支付接口 (4)
2.1.1 支付接口表单定义 (4)
2.1.2 tranData数据定义 (5)
2.1.3 tranData格式定义 (7)
2.1.4 表单样例 (7)
2.2 通知接口 (9)
2.2.1 通知接口表单定义 (9)
2.2.2 notifyData数据定义 (9)
2.2.3 notifyData格式定义 (10)
2.2.4 表单样例 (11)
2.3 说明 (12)
第 3 章安全API说明 (12)
第 4 章开发步骤 (12)
第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、银行作为交易的一方，支持众多商户和客户时，存在一定的带宽和服务器处理压力，使用客户返回商户方式提供交易结果，可有效减少交易掉单现象，只要客户到了银行的结果页面，如果还出现掉单问题，则可能是客户和商户的通讯等方面的问题。
以下简述处理流程：
客户
14
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表单数据如下：
注：
1、数据中不能包含“|”、“&”、“=”，这些字符为银行端程序保留字符；中文变量使用GBK 编码。
2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮中submit 不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：，则一定注意在引号内不要包含空格，不要写成“mer URL ”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付
3、接口名称和版本号一定要和上表中相同.。
4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。
5、tranData交易数据的xml串需要有xml的头，即
2.1.2tranData数据定义
2.1.3tranData格式定义
tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)
2.1.4表单样例
表单数据：
tranData对应的xml明文：
2.2通知接口
2.2.1通知接口表单定义
2.2.2notifyData数据定义
2.2.3notifyData格式定义
notifyData格式(xml格式固定，选输字段的取值可以为空，标签需保留)
2.2.4表单样例
表单数据：
notifyData对应的明文：
2.3说明
商户可能收到的银行通知
指令成功：
只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。
指令失败：
注意可能收到多笔失败。客户支付失败时可以重提此笔订单到银行支付。
指令可疑：
由于网银系统与后台业务处理系统间通讯异常，造成网银不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。
没有收到客户浏览器转发的银行通知：
由于客户浏览器端或互联网通讯等原因可能造成商户端接收不到客户浏览器提交的银行通知。当没有收到银行通知时，可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。
商户提交的订单信息和银行返回的通知消息都是xml串，并且进行了BASE64编码；
提交和返回的xml都应有xml头；
第3 章安全API说明
为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上文的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。安全API的使用方法可参见相关开发语言的说明和demo程序；
第4 章开发步骤
商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。
生成订单：
1、商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户
证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；
2、商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和
扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名）
3、商户进行开发，准备要求的订单数据；
4、其中订单签名数据merSignMsg字段是对明文的签名数据；需要使用提供的API函数和
商户私钥进行签名，得到签名串，然后做BASE64编码；
5、其中商城证书公钥merCert字段需要使用API函数做BASE64编码；
6、准备好订单数据，即完成订单提交的开发；之后只要将订单提交银行接收入口“https://
银行地址/servlet/ICBCINBSEBusinessServlet”，银行来处理B2C指令的资金支付；
接收通知：
交易处理后，会将客户定向回商户网站，此时包含交易结果信息和银行签名。商户接收到银行通知后，需使用开发API和银行公钥来验证银行签名，以确保通知消息的有效性，以下简要说明验证步骤：
1、获得各字段取值后，注意提交的明文需要进行base64解码才能获得。使用商户开发API
和银行公钥文件对表单中的银行签名signMsg进行验签；
2、验签成功后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关
键信息和自己记录的是否一致；
3、商户根据交易结果tranStat来更新自己的指令状态和相关数据库信息；