中国工商银行网上银行B2C在线支付接口说明
一、B2C流程说明：
1、客户在商户网站浏览商品信息，签订订单；
2、商户按照工行B2C订单数据规范形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接收商户B2C订单信息的servlet；
3、客户确认使用工行支付后，提交此表单到工行；
4、工行网银系统接收此笔B2C订单，对订单信息和商户信息进行检查，通过检查则显示工行B2C支付页面；
5、客户在此页面可以查询客户在银行的预留信息；也可以输入支付卡号、支付密码、验证码进行B2C支付；
6、工行检查客户信息，通过检查后显示确认页面；客户确认提交后工行进行支付指令处理；
7、工行进行支付指令处理后，如果商户需要工行实时通知，则工行将处理结果使用http协议post方式将通知消息数据提交到商户网站（这个接收银行通知消息的商户端地址是随商户订单数据提交银行的merURL字段），商户返回取货地址或关闭这个银行与其建立的连接后，银行才显示交易结果页面给客户。（注意1、发送通知和显示结果页面是串行的，所以商户端接收银行通知处理时间太长可能导致客户等待超时，造成银行不能将交易结果页面显示给客户。2、此连接是银行服务器自动和商户进行的连接，商户返回也是直接返回给银行，商户端不能对银行的这个请求进行重定向。）
8、工行进行支付指令处理后，如果商户不需要工行实时通知，则工行直接显示交易结果给客户。
二、B2C接口数据说明：
接口数据格式定义通过接口名称和接口版本号来标识，以便将来的扩展；以下数据格式为“1.0.0.0”版的“ICBC_PERBANK_B2C”接口定义。
2.1 B2C商户提交表单接口定义：
| 变量名称 |
变量命名 |
长度定义 |
说明 |
| 接口名称 |
interfaceName |
MAX(30) |
必输，签名， 取值：“ICBC_PERBANK_B2C” |
| 接口版本号 |
interfaceVersion |
MAX(15) |
必输，签名， 取值：“1.0.0.0” |
| 订单号 |
orderid |
MAX(30) |
必输，签名， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。 |
| 订单金额 |
amount |
MAX(10) |
必输，签名， 客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。 |
| 支付币种 |
curType |
=3 |
必输，签名， 用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。 取值：“001” |
| 商户代码 |
merID |
MAX(20) |
必输，签名， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。 |
| 商城账号 |
merAcct |
MAX(19) |
必输，签名， 商城收费入账账号（只能交易时指定）。 |
| 检验联名标志 |
verifyJoinFlag |
=1
|
必输，签名。 取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误； 取值“0”：不检验客户是否与商户联名，按上送金额扣帐。 |
| 通知类型 |
notifyType |
=2 |
必输，签名， 在交易转账处理完成后把交易结果通知商户的处理模式。 取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段； 取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的B2C商户服务网站，或者使用工行提供的客户端程序API主动获取通知信息。 |
| 接收支付结果信息通知程序地址 |
merURL |
MAX (200) |
选输，签名， 使用HS通知类型的商户用来接收工行订单支付结果的URL；银行使用HTTP协议POST方式向此地址发送通知信息；目前只支持80端口。 使用“AG”通知类型的商户,该字段可以为空或者不上送该字段；但在签名数据中必须包含此项，取值可为空。 取值举例：http://www.mer.com/getICBCPayResult.jsp |
| 结果发送类型 |
resultType |
=1
|
选输，签名。 取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息； 取值“1”，银行只向商户发送交易成功的通知信息。 只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。 |
| 商品编号 |
goodsID |
MAX(30) |
选输 |
| 商品名称 |
goodsName |
MAX(60) |
选输 |
| 商品数量 |
goodsNum |
MAX(10) |
选输 |
| 已含运费金额 |
carriageAmt |
MAX(10) |
选输 |
| 商城提示 |
merHint |
MAX(120) |
选输 |
| 交易日期时间 |
orderDate |
=14 |
必输，签名， 格式为：YYYYMMDDHHmmss 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。 |
| 订单签名数据 |
merSignMsg |
无限制 |
必输， 商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行签名，然后进行BASE64编码后得到的字符串。（格式单独说明） |
| 商城证书公钥 |
merCert |
无限制 |
必输， 商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。 |
| 备注字段1 |
remark1 |
MAX(100) |
选输 |
| 备注字段2 |
remark2 |
MAX(100) |
选输 |
注：
1、数据中不能包含“|”“&”“=”，此字符为银行端程序保留字符；中文变量使用GBK编码，另请注意与C2C接口定义字段名称和大小写有区分
2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮……>中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：merURL "value="http://www.merchant.com/ICBCPay/">，则一定注意在引号内不要包含空格，不要写成“mer URL”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付
3、接口名称和版本号一定要和上表中相同.。
4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。
2.2 商户提交表单签名merSignMsg格式：
1、组织要签名的数据串(顺序固定；被商户签名的串为各输入项的值)：
接口名称的值+接口版本号的值+商城代码的值+商城账号的值+通知地址的值+结果发送类型的值+订单号的值+订单金额的值+支付币种的值+通知类型的值+交易日期时间的值+校验联名标志的值
2、举例：
以下是需要签名的数据名称及对应值
interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&merID=0200EC20000012&merAcct=0200029109000030106&merURL=http://www.geticbcmsg.com.cn/servlet¬ifyType=HS&orderid=000000001&amount=100&curType=001&resultType=0&orderDate=20050801192556&verifyJoinFlag=0
需要签名的明文
ICBC_PERBANK_B2C1.0.0.00200EC200000120200029109000030106http://www.geticbcmsg.com.cn/servletHS0000000011000010200508011925560
签名后（用测试私钥user.key ）
merSignMsg为
SFVdS3Kca6d/wetLFwynBl1q5nDIyxxEUXCzniIa47mhxs1BM9mPsnRc2lOqqrfwBdwBjSE82jS/iBHYKolf2sppjEyOImVZycv96321QPDgPA1yleO83K1XA1rmB3zxsIuwLKIICSWwdttn1XPYOQLJ/WAtZ5DFYFog7J8pXw0=
merCert为（用测试证书user.crt）
MIICVjCCAb+gAwIBAgIKI9fKEDP6AAAO3DANBgkqhkiG9w0BAQUFADA0MRgwFgYDVQQDEw9wYmouaWNiYy5jb20uY24xGDAWBgNVBAoTD3Biai5pY2JjLmNvbS5jbjAeFw0yMDA5MjAwOTI3NDFaFw0yMTA5MjAwOTI3NDFaMEMxGDAWBgNVBAMTD2JpYW5sdTIyLmUuMDIwMDENMAsGA1UECxMEMDIwMDEYMBYGA1UEChMPcGJqLmljYmMuY29tLmNuMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDG+u/C5pad0ZbwvAk9Gv1rr+SpknfFUsTMhJLcI2KiYa+XLSf5vCib0OclOoDDXKIWPt/hkMEz+ED8YukQpsstXHvnxVFxVtPh23dubQjB8/kJ7X5EbwngsHMLFEXqr3UvNfcGZHuAFqMRPtr8ys3YnL3UG43Xienc3cD8jXFdQQIDAQABo2AwXjBLBgNVHR8ERDBCMECgPqA8pDowODEOMAwGA1UEAxMFY3JsMTMxDDAKBgNVBAsTA2NybDEYMBYGA1UEChMPcGJqLmljYmMuY29tLmNuMA8GA1UdYwQIAwYA/wAAAAAwDQYJKoZIhvcNAQEFBQADgYEAQe6tLhKaNX8OPNT2XzH7dTXIFmTm37hSvmbEL/Q/pWV386KVrNSCnyN3fowanMt5TE9qZFn9enVvyDJw4nAUx38F2PFn2Tt7JUtzt/pNKC5FiebpFJH48AXIP1Xt5GjdcBx0oXM9QNBtYvY0189t357EH4UaBfO+c+L8fkOt37o=
2.3 B2C通知商户交易结果接口定义：
| 变量名称 |
变量命名 |
长度定义 |
说明 |
| 接口名称 |
interfaceName |
MAX(30) |
取值：“ICBC_PERBANK_B2C” |
| 接口版本号 |
interfaceVersion |
MAX(15) |
取值：“1.0.0.0” |
| 订单号 |
orderid |
MAX(30) |
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。 |
| 银行指令序号 |
TranSerialNo |
MAX(30) |
银行端指令流水号 |
| 订单金额 |
amount |
MAX(10) |
客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。 |
| 支付币种 |
curType |
=3 |
用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。 取值：“001” |
| 商户代码 |
merID |
MAX(20) |
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。 |
| 商城账号 |
merAcct |
MAX(19) |
商城收费入账账号（只能交易时指定）。 |
| 检验联名标志 |
verifyJoinFlag |
=1
|
取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误； 取值“0”：不检验客户是否与商户联名，按上送金额扣帐。 |
| 客户联名标志 |
JoinFlag |
=1 |
客户在银行端是否与商城联名标志位。1客户联名 0客户未联名 |
| 联名会员号 |
UserNum |
MAX(40) |
联名客户在商户的会员号。 |
| 结果发送类型 |
resultType |
=1 |
取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息； 取值“1”，银行只向商户发送交易成功的通知信息。 |
| 交易日期时间 |
orderDate |
=14 |
格式为：YYYYMMDDHHmmss 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。 |
| 返回通知日期时间 |
notifyDate |
MAX(14) |
格式为：YYYYMMDDHHmmss |
| 订单处理状态 |
tranStat |
=1 |
1-“交易成功，已清算”； 2-“交易失败”； 3-“交易可疑” |
| 错误描述 |
comment |
MAX(100) |
错误描述 |
| 备注1 |
remark1 |
MAX(100) |
备注 |
| 备注2 |
remark2 |
MAX(100) |
备注 |
| 通知消息银行签名数据 |
signMsg |
无限制 |
银行使用自己证书对商户通知消息按照一定格式进行的签名,然后进行BASE64编码后的字符串。（格式单独描述） |
（注意与C2C通知接口定义变量名区分）
2.4 通知消息银行签名数据signMsg格式：
1、组织要签名的数据串(顺序固定；银行通知消息签名的串为以下格式，请注意与商户签名串的格式不同)：
接口名称=值&接口版本号=值&订单号=值&指令序号=值&订单金额=值&支付币种=值&商城代码=值&商城账号=值&校验联名标志=值&客户联名标志=值&联名会员号=值&结果发送类型=值&交易日期时间=值&返回通知日期时间=值&订单处理状态=值&错误描述=值&备注1=值&备注2=值
interfaceName=值&interfaceVersion=值&orderid=值&TranSerialNo=值&amount=值&curType=值&merID=值&merAcct=值&verifyJoinFlag=值&JoinFlag=值&UserNum=值&resultType=值&orderDate=值¬ifyDate=值&tranStat=值&comment=值&remark1=值
&remark2=值
举例：
以下是需要验签的数据串明文
interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&orderid=000000001&TranSerialNo=&amount=100&curType=001&merID=0200EC20000012&merAcct=0200029109000030106&verifyJoinFlag=0&JoinFlag=&UserNum=&resultType=0&orderDate=20050801192556¬ifyDate=20050824165910&tranStat=2&comment=failure,Error_code:32147ErrorMsg:提交支付表单时间数据不在有效时间范围。&remark1=&remark2=
签名后signMsg为
Yp4CVHY5rHtcQ9kOxHc70k1PKgpv1jXk0LZgSH0O+iEcFA3KKxBRjAhvCvV0hDc9X0WXswMfcGuaKMoCJSMHmdq3lVTYr2hfT1/K3nPI6IdCGmo4wJWha8ha4ujyLkQFa36f+7C1g9keBro59GPIBHHaRs1Ggmnb2aNimdMAAiM=
2.5 商户可能收到的银行通知：
指令成功：
只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。
指令失败：
注意可能收到多笔失败。客户支付失败时可以重提此笔订单到银行支付。
指令可疑：
由于网银系统与后台业务处理系统间通讯异常，造成网银不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。
没有收到银行通知：
由于银行、商户两端服务器或者互联网通讯等原因可能造成商户端接收不到银行通知。当没有收到银行通知时，可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。
2.6商户返回取货地址：
取货地址（也可称为商户收到银行成功支付后的商户端确认地址）：
如果有取货地址则及时返回取货地址，没有取货地址需及时关闭连接；因为银行端先进行订单支付清算，然后给商户发送通知，在商户返回取货地址或者关闭连接后，才显示交易结果给客户，整个过程是串行的；如果商户在收到银行通知后，不及时返回或关闭连接，将可能造成客户端等待超时，无法显示最终的交易结果页面。
三、安全API说明：
为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上一节的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。
安全API的使用方法可参见【开发API接口】目录中不同开发语言的说明和demo程序；
四、开发步骤
商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。
生成订单：
1、 商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；
2、 商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名）
3、 商户进行开发，准备【B2C商户提交表单接口定义】一节中要求的订单数据；
4、 其中订单签名数据merSignMsg字段需要根据【商户提交表单签名merSignMsg格式】一节中规定数据项和顺序来拼接成明文串；然后使用提供的API函数和商户私钥进行签名，得到签名串，然后做BASE64编码；
5、 其中商城证书公钥merCert字段需要使用API函数做BASE64编码；
6、 准备好订单数据，即完成订单提交的开发；之后只要将订单提交银行接收入口“https://银行地址/servlet/ICBCINBSEBusinessServlet”，银行来处理B2C指令的资金支付；
接收通知：
如果商户需要银行实时发送交易结果，则需要在订单的通知类型notifyType设置成“HS” ，并设置有效的接收银行通知的接收地址merURL字段，银行在支付处理完成后会向此地址post交易结果表单，表单数据项已在【B2C通知商户交易结果接口定义】中说明；
商户接收到银行通知后，需使用开发API和银行公钥来验证银行签名，以确保通知消息的有效性，以下简要说明验证步骤：
1、 商户收到银行通知，即接收到【B2C通知商户交易结果接口定义】中说明的各字段；各字段使用URLencode，如果商户端web服务器没有自动将各字段进行URLdecode，则商户程序需手工进行URL解码；
2、 获得各字段取值后，根据【通知消息银行签名数据signMsg格式】格式中说明的数据项和顺序，拼成银行端签名数据明文；
3、 使用商户开发API和银行公钥文件对表单中的银行签名signMsg进行验签；
4、 验签成功后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关键信息和自己记录的是否一致；
5、 商户根据交易结果tranStat来更新自己的指令状态和相关数据库信息；
6、 如果商户没有信息返回给银行则直接关闭此连接；如果商户需要提供客户取货地址或者希望客户到商户自己的确认页面，则需要返回取货地址或确认页面的URL给银行，银行将在显示给客户的交易结果页面显示此URL的链接供客户点击；
五、样例：
商户提交订单form
ACTION="https://银行地址/servlet/ICBCINBSEBusinessServlet">
1、订单只能使用POST方式提交；使用https协议通讯；
2、接收servlet名称固定为：/servlet/ICBCINBSEBusinessServlet
3、银行地址：如果是生产则为“mybank.icbc.com.cn”，若为模拟测试环境则为“mybank.dccnet.com.cn”
接口名称固定为“ICBC_PERBANK_B2C”
接口版本目前为“1.0.0.0”
订单号商户端产生，一天内不能重复。
金额以分为单位
币种目前只支持人民币，代码为“001”
银行提供
银行提供
“1”判断该客户是否与商户联名；取值“0”不检验客户是否与商户联名。
HS方式实时发送通知；AG方式不发送通知；
接收银行通知地址，目前只支持http协议80端口
value="0">
对于HS方式“0”：发送成功或者失败信息；“1”，只发送交易成功信息。
14位时间戳
商户签名数据BASE64编码
商户证书公钥BASE64编码
小毡帽">
金额以分为单位
跳楼甩卖！" size="60">
以上五个字段用于客户支付页面显示
备注字段
备注字段
注意商户提交订单数据不能提交接口中没有定义的字段，提交按钮不能设置name属性，如果设置了，提交按钮的值将作为一个变量提交，可能造成数据检查错误。
银行通知http报文：
（此样例为银行通知消息的http报文的数据内容部分，省略http报头）
interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&orderid=000000001&TranSerialNo=&amount=100&curType=001&merID=0200EC20000012&merAcct=0200029109000030106&verifyJoinFlag=0&JoinFlag=&UserNum=&resultType=0&orderDate=20050801192556¬ifyDate=20050824165910&tranStat=2&comment=failure,Error_code:32147ErrorMsg: