中国工商银行网上银行C2C在线支付接口说明V1001.docx

1、中国工商银行网上银行C2C在线支付接口说明V1001中国工商银行网上银行C2C在线支付接口说明一、C2C流程说明：1、客户在商户浏览商品信息，签订订单；2、商户按照工行C2C订单数据规形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接收商户C2C订单信息的servlet；3、客户确认使用工行支付后，提交此表单到工行；4、工行网银系统接收此笔C2C订单，对订单信息和商户信息进行检查，通过检查则显示工行C2C支付页面；5、客户在此页面可以查询客户在银行的预留信息；也可以输入支付卡号、支付密码、验证码进行C2C支付；6、工行检查

2、客户信息，通过检查后显示确认页面；客户确认提交后工行进行支付指令处理；7、工行进行支付指令处理后，如果商户需要工行实时通知，则工行将处理结果使用http协议post方式将通知消息数据提交到商户（这个接收银行通知消息的商户端地址是随商户订单数据提交银行的merURL字段），商户返回取货地址或关闭这个银行与其建立的连接后，银行才显示交易结果页面给客户。（注意1、发送通知和显示结果页面是串行的，所以商户端接收银行通知处理时间太长可能导致客户等待超时，造成银行不能将交易结果页面显示给客户。2、此连接是银行服务器自动和商户进行的连接，商户返回也是直接返回给银行，商户端不能对银行的这个请求进行重定向。）8

3、、工行进行支付指令处理后，如果商户不需要工行实时通知，则工行直接显示交易结果给客户。二、C2C接口数据说明：接口数据格式定义通过接口名称和接口版本号来标识，以便将来的扩展；以下数据格式为 “1.0.0.1”版的“ICBC_PERBANK_C2C”接口定义。C2C商户提交表单接口定义：1.0.0.1版本变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceNameMAX(30)必输，签名，取值：“ICBC_PERBANK_C2C”接口版本号interfaceVersionMAX(15)必输，签名，取值：“1.0.0.1”订单号orderIDMAX(30)必输，签名，客户支付后商户

4、产生的一个唯一的定单号，该订单号应该在相当长的时间不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。订单金额amountMAX(10)必输，签名，客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。商城收费金额merFeeAmtMAX(10)必输，签名，可为零，必需符合金额标准。支付币种curType= 3必输，签名，用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”商户代码merIDMAX(20)必输，签名，唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。商城账号merAcctMAX(19)必输，签名，商城收费入

5、账账号 （只能交易时指定）。卖家收款卡号venderCardNumMAX(19)必输，签名，支持工行灵通卡、E时代卡、理财金卡、信用卡、贷记卡；不支持国际卡卖家收款名称venderNameMAX(40)必输，签名。检验联名标志verifyJoinFlag=1必输，签名。取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。通知类型notifyType= 2必输，签名，在交易转账处理完成后把交易结果通知商户的处理模式。取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发

6、送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段；取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的C2C商户服务，或者使用工行提供的客户端程序API主动获取通知信息。接收支付结果信息通知程序地址merURLMAX (200)选输，签名，使用HS通知类型的商户用来接收工行订单支付结果的URL；银行使用HTTP协议POST方式向此地址发送通知信息；目前只支持80端口。使用“AG”通知类型的商户,该字段可以为空或者不上送该字段；但在签名数据中必须包含此项，取值可为空。取值举例：.mer./getICBCPayResult.jsp（注意需要写上“”）结果

7、发送类型resultType=1选输，签名。取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1”，银行只向商户发送交易成功的通知信息。只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。商品编号goodsIDMAX(30)选输商品名称goodsNameMAX(60)选输商品数量goodsNumMAX(10)选输已含运费金额carriageAmtMAX(18)选输商城提示merHintMAX(120)选输交易日期时间orderDate=14必输，签名，格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前1小时和后12

8、小时围，否则判定交易时间非法。订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行签名，然后进行BASE64编码后得到的字符串。（格式单独说明）商城证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。备注字段1remark1MAX(100)选输备注字段2remark2MAX(100)选输语言版本LanguageMAX(10)选输，默认为中文版取值：“EN_US”为英文版；取值：“ZH_CN”或其他为中文版。注意：大小写敏感。（注意数据值中不能包含“&”“=”，此字符为银行端程序保留字

9、符；中文变量使用GBK编码）商户提交表单签名merSignMsg格式：根据订单中各数据项，使用&符进行连接成签名明文，各字段顺序固定；每个数据项由变量名称加等号加变量值组成；如果变量值为空仍需保留字段位置； 格式说明如下：接口名称&接口版本号&订单号&订单金额&商城收费金额&支付币种&商城代码&商城账号&卖家收款卡号&卖家收款名称&校验联名标志&通知类型&通知地址&结果发送类型&交易日期时间interfaceName=值&interfaceVersion=值&orderID=值&amount=值&merFeeAmt=值&curType=值&merID=值&merAcct=值&venderCar

10、dNum=值& venderName =值&verifyJoinFlag=值¬ifyType=值&merURL=值&resultType=值&orderDate=值举例：interfaceName=ICBC_PERBANK_C2C &interfaceVersion=1.0.0.0&orderID=001&amount=99999999&merFeeAmt=10000&curType=001&merID=ABC001&merAcct=31&venderCardNum=20&三&verifyJoinFlag=0¬ifyType=AG&merURL=&resultType=&order

11、Date=334C2C通知商户交易结果接口定义：1.0.0.1版本变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceNameMAX(30)取值：“ICBC_PERBANK_C2C”接口版本号interfaceVersionMAX(15)取值：“1.0.0.1”订单号orderIDMAX(30)客户支付后商户产生的一个唯一的定单号，该订单号应该在相当长的时间不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。银行指令序号TranSerialNoMAX(30)银行端指令流水号订单金额amountMAX(10)客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必

12、需符合金额标准。商城收费金额merFeeAmtMAX(10)可为零，必需符合金额标准。支付币种curType= 3用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”商户代码merIDMAX(20)唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。商城账号merAcctMAX(19)商城收费入账账号 （只能交易时指定）。卖家收款卡号venderCardNumMAX(19)支持工行灵通卡、E时代卡、理财金卡、信用卡、贷记卡；不支持国际卡卖家收款名称venderNameMAX(40)卖家收款名称买家付款卡号customCardNumMAX(19)“付款卡号”

13、后四位进行隐含如：2413*买家付款名称customNameMAX(20)“付款人名”从第二位汉字开始隐含，如：*检验联名标志verifyJoinFlag=1取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。客户联名标志JoinFlag=1客户在银行端是否与商城联名标志位。1客户联名 0客户未联名联名会员号UserNumMAX(40)联名客户在商户的会员号。结果发送类型resultType=1取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1”，银行只向商户发送交易成功的通知

14、信息。交易日期时间orderDate=14格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前1小时和后12小时围，否则判定交易时间非法。返回通知日期时间notifyDateMAX(14)格式为：YYYYMMDDHHmmss订单处理状态tranStat=11-“交易成功，已清算”；2-“交易失败”；3-“交易可疑”错误描述commentMAX(100)错误描述备注1remark1MAX(100)备注备注2remark2MAX(100)备注通知消息银行签名数据bankSignMsg无限制银行使用自己证书对商户通知消息按照一定格式进行的签名,然后进行BASE64编码后的字符串。（格式单独

15、描述）通知消息银行签名数据bankSignMsg格式：根据消息中各数据项，使用&符进行连接成银行端签名明文，各字段顺序固定；每个数据项由变量名称加等号加变量值组成；如果变量值为空仍保留字段位置；格式说明：接口名称&接口版本号&订单号&指令序号&订单金额&商城收费金额&支付币种&商城代码&商城账号&卖家收款卡号&卖家收款名称&买家收款卡号&买家付款名称&校验联名标志 &客户联名标志&联名会员号&结果发送类型&交易日期时间&返回通知日期时间&订单处理状态&错误描述&备注1&备注2interfaceName=值&interfaceVersion=值&orderID=值& TranSerialNo =

16、值&amount=值&merFeeAmt=值&curType=值&merID=值&merAcct=值&venderCardNum=值&venderName =值&customCardNum=值&customName=值&verifyJoinFlag=值&JoinFlag=值&UserNum =值&resultType=值&orderDate=值¬ifyDate=值&tranStat=值&comment=值remark1=值& remark2=值提示：以上格式为银行端签名明文格式，对于银行签名字段bankSignMsg，得到密文后进行了BASE64编码，所有字段在发出前取值部分都经过url

17、Ecode编码（包括bankSignMsg字段）。商户可能收到的银行通知：指令成功：只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。指令失败：注意可能收到多笔失败。客户支付失败时可以重提此笔订单到银行支付。指令可疑：由于网银系统与后台业务处理系统间通讯异常，造成网银不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。没有收到银行通知：由于银行、商户两端服务器或者互联网通讯等原因可能造成商户端接收不到银行通知。当没有收到银行通知时，可登录工行商户服务手工查询指令状态或者商户调用查询接口自动处理。商户返回取货地址：取货地址（也可

18、称为商户收到银行成功支付后的商户端确认地址）：如果有取货地址则及时返回取货地址，没有取货地址需及时关闭连接；因为银行端先进行订单支付清算，然后给商户发送通知，在商户返回取货地址或者关闭连接后，才显示交易结果给客户，整个过程是串行的；如果商户在收到银行通知后，不及时返回或关闭连接，将可能造成客户端等待超时，无法显示最终的交易结果页面。如果商户端接收到银行通知消息，进行后续检查和处理时，商户自己程序出现异常，不应将错误信息返回给银行。银行只接收取货地址的返回，商户程序异常时，应及时关闭和银行的连接。如果商户返回其他非取货地址的信息，银行端将验证返回信息不是有效的URL而记录错误日志，在给客户的交易

19、结果页面不会有商户返回的容。三、安全API说明：为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上一节的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。安全API的使用方法可参见【开发API接口】目录中不同开发语言的说明和demo程序；四、开发步骤商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。生成订单：1、 商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生

20、成商户证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；2、 商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名）3、 商户进行开发，准备【C2C商户提交表单接口定义】一节中要求的订单数据；4、 其中订单签名数据merSignMsg字段需要根据【商户提交表单签名merSignMsg格式】一节中规定数据项和顺序来拼接成明文串；然后使用提供的API函数和商户私钥进行签名，得到签名串，然后做BASE64编码；5、 其中商城证书公钥merCert字段需要

21、使用API函数做BASE64编码；6、 准备好订单数据，即完成订单提交的开发；之后只要将订单提交银行接收入口“https:/银行地址/servlet/ICBCINBSEBusinessServlet”，银行来处理C2C指令的资金支付；接收通知：如果商户需要银行实时发送交易结果，则需要在订单的通知类型notifyType设置成“HS” ，并设置有效的接收银行通知的接收地址merURL字段，银行在支付处理完成后会向此地址post交易结果表单，表单数据项已在【C2C通知商户交易结果接口定义】中说明；商户接收到银行通知后，需使用开发API和银行公钥来验证银行签名，以确保通知消息的有效性，以下简要说明验

22、证步骤：1、 商户收到银行通知，即接收到【C2C通知商户交易结果接口定义】中说明的各字段；各字段使用URLencode，如果商户端web服务器没有自动将各字段进行URLdecode，则商户程序需手工进行URL解码；2、 获得各字段取值后，根据【通知消息银行签名数据bankSignMsg格式】格式中说明的数据项和顺序，拼成银行端签名数据明文；3、 使用商户开发API和银行公钥文件对表单中的银行签名bankSignMsg进行验签；4、 验签成功后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关键信息和自己记录的是否一致；5、 商户根据交易结果tranStat来更新自己的指令状态和

23、相关数据库信息；6、 如果商户没有信息返回给银行则直接关闭此连接；如果商户需要提供客户取货地址或者希望客户到商户自己的确认页面，则需要返回取货地址或确认页面的URL给银行，银行将在显示给客户的交易结果页面显示此URL的供客户点击；五、样例：商户提交订单form1、订单只能使用POST方式提交；使用https协议通讯；2、接收servlet名称固定为：/servlet/ICBCINBSEBusinessServlet3、银行地址：如果是生产则为“”，若为模拟测试环境则为“”接口名称固定为“ICBC_PERBANK_C2C”接口版本目前为“1.0.0.0”订单号商户端产生，一天不能重复。金额以分为

24、单位金额以分为单位币种目前只支持人民币，代码为“001”银行提供银行提供工行牡丹卡中文使用GBK编码“1”判断该客户是否与商户联名；取值“0”不检验客户是否与商户联名。HS方式实时发送通知；AG方式不发送通知；接收银行通知地址，目前只支持http协议80端口当通知方式是“HS”是有效；取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1”，银行只向商户发送交易成功的通知信息。14位时间戳商户签名数据BASE64编码商户证书公钥BASE64编码 以上五个字段用于客户支付页面显示备注字段备注字段Language, EN_US为英文版 注意商户提交订单数据不能提交接口中没有定义的

25、字段，提交按钮不能设置name属性，如果设置了，提交按钮的值将作为一个变量提交，可能造成数据检查错误。银行通知http报文：（此样例为银行通知消息的http报文的数据容部分，省略http报头）interfaceName=ICBC_PERBANK_C2C&interfaceVersion=1.0.0.0&orderID=001&TranSerialNo=10805500&amount=2000&merFeeAmt=1&curType=001&merID=0200EC30000011&merAcct=79&venderCardNum=09&venderName=%D5%D4%C0%DA&customCardNum=&customName=&verifyJoinFlag=0&JoinFlag=&UserNum=&resultType=0&orderDate=413¬ifyDate=459&tranStat=&comment=3