2024年1月31日发(作者：)
B2C支付接口v1.0.0.3
中国工商银行软件开发中心
Copyright Reserved
目录
商户第 1 章 业务说明 ............................................. 1
手册第 2 章 商户接口 ............................................. 4
2.1 支付接口 ............................................. 4
2.1.1 支付接口表单定义 .................................... 4
2.1.2 tranData数据定义 ................................... 7
2.1.3 tranData格式定义 .................................. 10
2.1.4 表单样例 ........................................... 11
2.2 通知接口 ............................................ 14
2.2.1 通知接口表单定义 ................................... 14
2.2.2 notifyData数据定义 ................................ 15
2.2.3 notifyData格式定义 ................................ 17
2.2.4 表单样例 ........................................... 18
2.3 说明 ................................................ 20
第 3 章 安全API说明 ........................................ 21
第 4 章 开发步骤 ............................................ 21
第 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、银行作为交易的一方，支持众多商户和客户时，存在一定的带宽和服务器处理压力，使用客户返回商户方式提供交易结果，可有效减少交易掉单现象，只要客户到了银行的结果页面，如果还出现掉单问题，则可能是客户和商户的通讯等方面的问题。
以下简述处理流程：
第 2 页
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（支持英文界面）
第 3 页
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形式；
第 4 页
FORM表单数据如下：
变量名称
接口名称
变量命名
长度定义
说明
必输，
取值：“ICBC_PERBANK_B2C”
必输，
取值：“1.0.0.3”
无限制
必输，签名；
整合所有交易数据形成的xml明文串，并做BASE64编码；
具体格式定义见下文；
注意：
需有xml头属性；整个字段使用BASE64编码；
xml明文中没有回车换行和多余空格；
订单签名数merSignMsg
据
无限制
必输，
商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg；
第 5 页
interfaceNamMAX(30)
e
接口版本号
interfaceVerMAX(15)
sion
交易数据
tranData
注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串；
商城证书公merCert
钥
无限制
必输，
商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串；
注：
1、数据中不能包含“|”、“&”、“=”，这些字符为银行端程序保留字符；中文变量使用GBK编码。
2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：merCert " value="xxxxxxx">，则一定注意在引号内不要包含空格，不要写成“mer URL ”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付
3、接口名称和版本号一定要和上表中相同.。
4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。
5、tranData交易数据的xml串需要有xml的头，即
encoding="GBK" standalone="no"?>
第 6 页
2.1.2
tranData数据定义
变量名称
接口名称
变量命名
长度定义
说明
必输，
取值：“ICBC_PERBANK_B2C”
必输，
取值：“1.0.0.3”
=14
必输，
格式为：YYYYMMDDHHmmss
要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。
订单号
orderid
MAX(30)
必输，
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。
订单金额
amount
MAX(10)
必输，
客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。
interfaceNam＝16
e
接口版本号
interfaceVerMAX(15)
sion
交易日期时orderDate
间
第 7 页
支付币种
curType
= 3
必输，
用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。
取值： “001”
商户代码
merID
MAX(20)
必输，
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
商户账号
merAcct
MAX(19)
必输，
商户入账账号，只能交易时指定。（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）
检验联名标verifyJoinFl=1
志
ag
必输，
取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；
取值“0”：不检验客户是否与第 8 页
商户联名，按上送金额扣帐。
语言版本
Language
MAX(10)
选输，默认为中文版
取值：“EN_US”为英文版；
取值：“ZH_CN”或其他为中文版。
注意：大小写敏感。
商品编号
商品名称
商品数量
goodsID
goodsName
goodsNum
MAX(30)
MAX(60)
MAX(10)
MAX(10)
选输
选输
选输
选输
已含运费金carriageAmt
额
商城提示
备注字段1
备注字段2
merHint
remark1
remark2
MAX(120)
MAX(100)
MAX(100)
MAX(1024)
选输
选输 单位：字节
选输 单位：字节
必输
必须合法的URL，交易结束，将客户引导到商户的此url，即通过客户浏览器post交易结果信息到商户的此URL
返回商户merURL
URL
返回商户变merVAR
量
MAX(1024)
选输
商户自定义，当返回银行结果时，作为一个隐藏域变量，商第 9 页
户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64
2.1.3
tranData格式定义
tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)
第 10 页
2.1.4
表单样例
表单数据：
S4wIiBlbmNvZGluZz0iR0JLIiBzdGFuZGFsb25lPSJubyI/PjxCMkNSZXE+PGludGVyZmFjZU5hbWU+SUNCQ19QRVJCQU5LX0IyQzwvaW50ZXJmYWNlTmFtZT48aW50ZXJmYWNlVmVyc2lvbj4xLjAuMC4zPC9pbnRlcmZhY2VWZXJzaW9uPjxvcmRlckluZm8+PG9yZGVyRGF0ZT4yMDA3MDcyNTEwNTAxNDwvb3JkZXJEYXRlPjxvcmRlcmlkPjIwMDcwNzI1MTA1MDE0LTIxMzQwNjI1NDg8L29yZGVyaWQ+PGFtb3VudD4yMDwvYW1vdW50PjxjdXJUeXBlPjAwMTwvY3VyVHlwZT48bWVySUQ+MDIwMEVDMjAwMDA4NzU8L21lcklEPjxtZXJBY2N0PjAyMDAwMjA0MDkwMTUwMjkxMzA8L21lckFjY3Q+PC9vcmRlckluZm8+PGN1c3RvbT48dmVyaWZ5Sm9pbkZsYWc+MDwvdmVyaWZ5Sm9pbkZsYWc+PExhbmd1YWdlPlpIX0NOPC9MYW5ndWFnZT48L2N1c3RvbT48bWVzc2FnZT48Z29vZHNJRD4wMDE8L2dvb2RzSUQ+PGdvb2RzTmFtZT7N/sTh0Nw8L2dvb2RzTmFtZT48Z29vZHNOdW0+MjwvZ29vZHNOdW0+PGNhcnJpYWdlQW10PjIwPC9jYXJyaWFnZUFtdD48bWVySGludD7H67GjwfSw/NewPC9tZXJIaW50PjxyZW1hcmsxPjwvcmVtYXJrMT48cmVtYXJrMj48L3JlbWFyazI+PG1lclVSTD5odHRwOi8vbG9jYWxob3N0OjkwODEvTmV3YjJjX1BheV9NZXIuanNwPC9tZXJVUkw+PG1lclZBUj50ZXN0PC9tZXJWQVI+PC9tZXNzYWdlPjwvQjJDUmVxPg==">
Fw0xODAzMTAwNzI0MTdaMD4xEzARBgNVBAMTCnBhbi5lLjAyMDAxDTALBgNVBAsTBDAyMDAxGDAWBgNVBAoTD3Biai5pY2JjLmNvbS5jbjCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAqBdQrbNWE61+forNFMGI/MmXxKY58P39YO4vzLpHCTHNGRwJKIwILMEOND88vh7cXTBY8kbt3vt0N+4pJY3iwKQA0GfuLfv5EjrsstyUohhogoxNAwxdbOLUTnn1ejNjwelZch4GqdkgmRzu6uTywRGW//foiUNgR/yL7Q2FcV0CAwEAAaNgMF4wSwYDVR0fBEQwQjBAoD6gPKQ6MDgxDjAMBgNVBAMTBWNybDIxMQwwCgYDVQQLEwNjcmwxGDAWBgNVBAoTD3Biai5pY2JjLmNvbS5jbjAPBgNVHWMECAMGAP8AAAAAMA0GCSqGSIb3DQEBBQUAA4GBAOImQhTOiQxHABUefFShrD1u3N2GhVP6JnyNUOAfI40WqxszjyfmRmhYPQUQc+8fMf52mcYXiVaEM4BVuRLPkCaybBwI0ykS+xBNMhy72naQPCeR+NNyZ4xduv/E5UE+INJrjnOHR7UWRBzdxX9bjsFB16beUVir7+S+adaXyQFT">
tranData对应的xml明文：
//localhost:9081/Newb2c_Pay_
2.2
通知接口
2.2.1
通知接口表单定义
变量名称
变量命名
长度定义
无限制
说明
取值：商户提交接口中merVAR字段当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64，银行端将此字段原样返回
通知结果数notifyData
据
无限制
银行通知消息，xml格式定义见下文，提交商户时对xml明文串进行了base64编码；
xml串中没有回车换行和多余空格；包含xml头属性，且格式固定；
银行对通知signMsg
无限制
第 14 页
银行使用自己证书对商户通知返回商户变merVAR
量
结果的签名数据
消息notifyData字段的xml格式明文串进行的签名，然后进行BASE64编码后的字符串。
注意：签名是对notifyData的xml明文进行签名，不是其BASE64编码后的串；签名后得到二进制数据，对此数据进行BASE64编码得到signMsg
2.2.2
notifyData数据定义
变量名称
接口名称
变量命名
长度定义
说明
取值：“ICBC_PERBANK_B2C”
interfaceNam＝16
e
接口版本号
interfaceVerMAX(15)
sion
交易日期时orderDate
间
=14
取值：“1.0.0.3”
格式为：YYYYMMDDHHmmss
要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。
订单号
orderid
MAX(30)
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。第 15 页
工行通过订单号加订单日期来唯一确认一笔订单的重复性。
订单金额
amount
MAX(10)
客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。
支付币种
curType
= 3
用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。
取值： “001”
商户代码
merID
MAX(20)
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
商户账号
merAcct
MAX(19)
商户收费入账账号 （只能交易时指定）。
检验联名标verifyJoinFl=1
志
ag
取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；
取值“0”：不检验客户是否与商户联名，按上送金额扣帐。
客户联名标JoinFlag
志
=1
客户在银行端是否与商城联名标志位。1客户联名 0客户未第 16 页
联名
联名会员号
UserNum
MAX(40)
联名客户在商户的会员号。
银行端指令流水号
银行指令序TranSerialNo
MAX(30)
号
返回通知日notifyDate
期时间
订单处理状tranStat
态
=1
MAX(14)
格式为：YYYYMMDDHHmmss
1-“交易成功，已清算”；
2-“交易失败”；
3-“交易可疑”
错误描述
comment
MAX(100)
错误描述
2.2.3
notifyData格式定义
notifyData格式(xml格式固定，选输字段的取值可以为空，标签需保留)
第 17 页
2.2.4
表单样例
表单数据：
lPjxpbnRlcmZhY2VWZXJzaW9uPjEuMC4wLjM8L2ludGVyZmFjZVZlcnNpb24+PG9yZGVySW5mbz48b3JkZXJEYXRlPjIwMDcwNzI1MTA1MDE0PC9vcmRlckRhdGU+PG9yZGVyaWQ+MjAwNzA3MjUxMDUwMTQtMjEzNDA2MjU0ODwvb3JkZXJpZD48YW1vdW50PjIwPC9hbW91bnQ+PGN1clR5cGU+MDAxPC9jdXJUeXBlPjxtZXJJRD4wMjAwRUMyMDAwMDg3NTwvbWVySUQ+PG1lckFjY3Q+MDIwMDAyMDQwOTAxNTAyOTEzMDwvbWVyQWNjdD48L29yZGVySW5mbz48Y3VzdG9tPjx2ZXJpZnlKb2luRmxhZz4wPC92ZXJpZnlKb2luRmxhZz48Sm9pbkZsYWc+PC9Kb2luRmxhZz48VXNlck51bT48L1VzZXJOdW0+PC9jdXN0b20+PGJhbms+PFRyYW5TZXJpYWxObz48L1RyYW5TZXJpYWxObz48bm90aWZ5RGF0ZT4yMDA3MDcyNTExMDQwMDwvbm90aWZ5RGF0ZT48dHJhblN0YXQ+MTwvdHJhblN0YXQ+PGNvbW1lbnQ+vbvS17PJuaajoTwvY29tbWVudD48L2Jhbms+PC9CMkNSZXM+">
notifyData对应的明文：
rifyJoinFlag>0
2.3
说明
商户可能收到的银行通知
指令成功：
只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。
指令失败：
注意可能收到多笔失败。客户支付失败时可以重提此笔订单到银行支付。
指令可疑：
由于网银系统与后台业务处理系统间通讯异常，造成网银不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。
没有收到客户浏览器转发的银行通知：
由于客户浏览器端或互联网通讯等原因可能造成商户端接收不到客户浏览器提交的银行通知。当没有收到银行通知时，可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。
商户提交的订单信息和银行返回的通知消息都是xml串，并且进行了第 20 页
BASE64编码；
提交和返回的xml都应有xml头；
第 3 章
安全API说明
为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上文的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。安全API的使用方法可参见相关开发语言的说明和demo程序；
第 4 章
开发步骤
商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。
生成订单：
1、
商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；
2、
商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名）
3、
商户进行开发，准备要求的订单数据；
4、
其中订单签名数据merSignMsg字段是对明文的签名数据；需要使用提第 21 页
供的API函数和商户私钥进行签名，得到签名串，然后做BASE64编码；
5、
其中商城证书公钥merCert字段需要使用API函数做BASE64编码；
6、
准备好订单数据，即完成订单提交的开发；之后只要将订单提交银行接收入口“银行地址/servlet/ICBCINBSEBusinessServlet”，银行来处理B2C指令的资金支付；
接收通知：
交易处理后，会将客户定向回商户网站，此时包含交易结果信息和银行签名。商户接收到银行通知后，需使用开发API和银行公钥来验证银行签名，以确保通知消息的有效性，以下简要说明验证步骤：
1、
获得各字段取值后，注意提交的明文需要进行base64解码才能获得。使用商户开发API和银行公钥文件对表单中的银行签名signMsg进行验签；
2、
验签成功后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关键信息和自己记录的是否一致；
3、
商户根据交易结果tranStat来更新自己的指令状态和相关数据库信息；
4、
希望以上资料对你有所帮助，附励志名3条：
5、
1、积金遗于子孙，子孙未必能守；积书于子孙，子孙未必能读。不如积阴德于冥冥之中，此乃万世传家之宝训也。
6、
2、积德为产业，强胜于美宅良田。
7、
3、能付出爱心就是福，能消除烦恼就是慧。
8、
第 22 页
发布评论