工行B2C在线支付接口说明.pdf

《工行B2C在线支付接口说明.pdf》由会员分享，可在线阅读，更多相关《工行B2C在线支付接口说明.pdf（10页珍藏版）》请在得力文库 - 分享文档赚钱的网站上搜索。

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

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

3、连接， 商户返回也是直接返回给银行，商户端不能对银行的这个请求进行重定向。 ）8、工行进行支付指令处理后，如果商户不需要工行实时通知，则工行直接显示交易结果给客户。二、二、B2CB2C 接口数据说明：接口数据说明：接口数据格式定义通过接口名称和接口版本号来标识，以便将来的扩展；以下数据格式为“1.0.0.0”版的“ICBC_PERBANK_B2C”接口定义。2.1 B2C2.1 B2C 商户提交表单接口定义：商户提交表单接口定义：变量名称接口名称接口版本号订单号变量命名interfaceName长度定义MAX(30)说明必输，签名，取值： “ICBC_PERBANK_B2C”必输，签名，取值：

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

5、：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0” ：不检验客户是否与商户联名，按上送金额扣帐。必输，签名，在交易转账处理完成后把交易结果通知商户的处理模式。取值“HS”：在交易完成后实时将通知信息以 HTTP 协议 POST 方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL 即表单中的 merURL 字段；取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的B2C 商户服务网站，或者使用工行提供的客户端程序 API 主动获取通知信息。选输，签名，使用 HS 通知类型的商户用来接收工行订单支付结果的URL；银

6、行使用HTTP 协议 POST 方式向此地址发送通知信息；目前只支持 80 端口。使用“AG”通知类型的商户,该字段可以为空或者不上送该字段；但在签支付币种curType= 3商户代码merIDMAX(20)商城账号merAcctMAX(19)检验联名标志verifyJoinFlag=1通知类型notifyType= 2接收支付结果信息通知程序地址merURLMAX (200)名数据中必须包含此项， 取值可为空。取值举例：http:/ ：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1” ，银行只向商户发送交易成功的通知信息。只有通知方式为 HS 时此值有效，如果使用 AG 方式，

7、可不上送此项，但签名数据中必须包含此项，取值可为空。选输选输选输选输选输必输，签名，格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前 1 小时和后 12 小时范围内， 否则判定交易时间非法。必输，商户使用工行提供的签名API 接口和商户证书将交易数据按一定格式进行签名，然后进行 BASE64 编码后得到的字符串。 （格式单独说明）必输，商户用二进制方式读取证书公钥文件后，进行 BASE64 编码后产生的字符串。选输选输goodsID商品名称goodsName商品数量goodsNum已含运费金额carriageAmt商城提示merHint交易日期时间orderDate商品编号MAX

8、(30)MAX(60)MAX(10)MAX(10)MAX(120)=14订单签名数据merSignMsg无限制商城证书公钥merCert无限制备注字段 1备注字段 2remark1remark2MAX(100)MAX(100)注：1、数据中不能包含“|” “&” “=” ，此字符为银行端程序保留字符；中文变量使用GBK 编码，另请注意与 C2C 接口定义字段名称和大小写有区分2、从商户 Post 过来的数据，参数名的名称必须与上表中完全相同参数名的名称必须与上表中完全相同，名称中的字母大小写名称中的字母大小写均要相同，不能进行随意更改均要相同，不能进行随意更改 ( (在在 formform 中

9、的提交按钮中的提交按钮 input type= 中中submitsubmit 不能有不能有 NameName 属性属性) )；此外，如果其他 inputinput 项的 Name 中使用了双引号，如：，则一定注意在引号内不要包含空格，不要写成“mer URL ” ，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付3、接口名称和版本号一定要和上表中相同.。4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。2.22.2 商户提交表单签名商户提交表单签名 merSignMsgmerSignMsg 格式：格式：1、组织要签名的数据串 (顺序固定；被商户签

10、名的串为各输入项的值)：接口名称的值+接口版本号的值+商城代码的值+商城账号的值+通知地址的值+结果发送类型的值+订单号的值+订单金额的值+支付币种的值+通知类型的值+交易日期时间的值+校验联名标志的值2、举例：以下是需要签名的数据名称及对应值interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&merID=0200EC20000012&merAcct=0200029109000030106&merURL=http:/ &resultType=0&orderDate=20050801192556& verifyJoinFlag=0需要签

11、名的明文ICBC_PERBANK_B2C1.0.0.00200EC200000120200029109000030106http:/ user.key ）merSignMsg 为SFVdS3Kca6d/wetLFwynBl1q5nDIyxxEUXCzniIa47mhxs1BM9mPsnRc2lOqqrfwBdwBjSE82jS/iBHYKolf2sppjEyOImVZycv96321QPDgPA1yleO83K1XA1rmB3zxsIuwLKIICSWwdttn1XPYOQLJ/WAtZ5DFYFog7J8pXw0=merCert 为（用测试证书 user.crt）MIICVjCCAb+gAw

12、IBAgIKI9fKEDP6AAAO3DANBgkqhkiG9w0BAQUFADA0MRgwFgYDVQQDEw9wYmouaWNiYy5jb20uY24xGDAWBgNVBAoTD3Biai5pY2JjLmNvbS5jbjAeFw0yMDA5MjAwOTI3NDFaFw0yMTA5MjAwOTI3NDFaMEMxGDAWBgNVBAMTD2JpYW5sdTIyLmUuMDIwMDENMAsGA1UECxMEMDIwMDEYMBYGA1UEChMPcGJqLmljYmMuY29tLmNuMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDG+u/C5pad0ZbwvA

13、k9Gv1rr+SpknfFUsTMhJLcI2KiYa+XLSf5vCib0OclOoDDXKIWPt/hkMEz+ED8YukQpsstXHvnxVFxVtPh23dubQjB8/kJ7X5EbwngsHMLFEXqr3UvNfcGZHuAFqMRPtr8ys3YnL3UG43Xienc3cD8jXFdQQIDAQABo2AwXjBLBgNVHR8ERDBCMECgPqA8pDowODEOMAwGA1UEAxMFY3JsMTMxDDAKBgNVBAsTA2NybDEYMBYGA1UEChMPcGJqLmljYmMuY29tLmNuMA8GA1UdYwQIAwYA/wAAAAAwDQYJKo

14、ZIhvcNAQEFBQADgYEAQe6tLhKaNX8OPNT2XzH7dTXIFmTm37hSvmbEL/Q/pWV386KVrNSCnyN3fowanMt5TE9qZFn9enVvyDJw4nAUx38F2PFn2Tt7JUtzt/pNKC5FiebpFJH48AXIP1Xt5GjdcBx0oXM9QNBtYvY0189t357EH4UaBfO+c+L8fkOt37o=2.3 B2C2.3 B2C 通知商户交易结果接口定义：通知商户交易结果接口定义：变量名称接口名称变量命名interfaceName长度定义MAX(30)说明取值： “ICBC_PERBANK_B2C”接口版本号订单号i

15、nterfaceVersionMAX(15)MAX(30)orderid取值： “1.0.0.0”客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。银行端指令流水号客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。取值： “001”唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。商城收费入账账号（只能交易时指定） 。取值“1” ：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取

16、值“0” ：不检验客户是否与商户联名，按上送金额扣帐。客户在银行端是否与商城联名标志位。1 客户联名 0 客户未联名联名客户在商户的会员号。取值“0” ：无论支付成功或者失败，银行都向商户发送交易通知信息；取值“1” ，银行只向商户发送交易成功的通知信息。格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前 1 小时和后 12 小时范围内， 否则判定交易时间非法。格式为：YYYYMMDDHHmmss1-“交易成功，已清算” ；2-“交易失败” ；3-“交易可疑”错误描述备注备注银行使用自己证书对商户通知消息按照一定格式进行的签名,然后进行银行指令序号订单金额TranSerialNoa

17、mountMAX(30)MAX(10)支付币种curType= 3商户代码商城账号检验联名标志merIDmerAcctverifyJoinFlagMAX(20)MAX(19)=1客户联名标志JoinFlag=1联名会员号结果发送类型UserNumMAX(40)=1resultType交易日期时间orderDate=14返回通知日期时间订单处理状态notifyDatetranStatMAX(14)=1comment备注 1remark1备注 2remark2通知消息银行signMsg错误描述签名数据MAX(100)MAX(100)MAX(100)无限制BASE64 编码后的字符串。 （格式单独描

18、述）（注意与 C2C 通知接口定义变量名区分）2.42.4 通知消息银行签名数据通知消息银行签名数据 signMsgsignMsg 格式：格式：1、组织要签名的数据串 (顺序固定；银行通知消息签名的串为以下格式，请注意与商户签名串的格式不同)：接口名称=值&接口版本号=值&订单号=值&指令序号=值&订单金额=值&支付币种=值&商城代码=值&商城账号=值&校验联名标志=值&客户联名标志=值&联名会员号=值&结果发送类型=值&交易日期时间=值&返回通知日期时间=值&订单处理状态=值&错误描述=值&备注 1=值&备注 2=值interfaceName=值&interfaceVersion=值&ord

19、erid=值&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

20、=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+iEcF

21、A3KKxBRjAhvCvV0hDc9X0WXswMfcGuaKMoCJSMHmdq3lVTYr2hfT1/K3nPI6IdCGmo4wJWha8ha4ujyLkQFa36f+7C1g9keBro59GPIBHHaRs1Ggmnb2aNimdMAAiM=2.52.5 商户可能收到的银行通知：商户可能收到的银行通知：指令成功：只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。指令失败：注意可能收到多笔失败。客户支付失败时可以重提此笔订单到银行支付。指令可疑：由于网银系统与后台业务处理系统间通讯异常， 造成网银不能确认支付指令结果， 则此笔指令为可疑指令；可疑指令将被自动批复，

22、商户、客户可于第二日查询指令状态。没有收到银行通知：由于银行、商户两端服务器或者互联网通讯等原因可能造成商户端接收不到银行通知。当没有收到银行通知时， 可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。2.62.6 商户返回取货地址：商户返回取货地址：取货地址（也可称为商户收到银行成功支付后的商户端确认地址） ：如果有取货地址则及时返回取货地址， 没有取货地址需及时关闭连接； 因为银行端先进行订单支付清算，然后给商户发送通知， 在商户返回取货地址或者关闭连接后， 才显示交易结果给客户，整个过程是串行的；如果商户在收到银行通知后，不及时返回或关闭连接，将可能造成客户端等待超时，

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

24、和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户证书（pfx 格式） ；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用） ；2、 商户或者银行用证书拆分工具将 pfx 格式的商户证书拆分成扩展名为 crt 的公钥文件和扩展名为 key 的私钥文件； （这两个文件用于商户开发 API 调用来进行商户订单数据签名）3、 商户进行开发，准备【B2C 商户提交表单接口定义】一节中要求的订单数据；4、 其中订单签名数据 merSignMsg 字段需要根据 【商户提交表单签名 merSignMsg 格式】 一节中规定数据项和顺序来拼接成明文串；然后使用提供的 AP

25、I 函数和商户私钥进行签名，得到签名串，然后做BASE64 编码；5、 其中商城证书公钥 merCert 字段需要使用 API 函数做 BASE64 编码；6、 准备好订单数据， 即完成订单提交的开发； 之后只要将订单提交银行接收入口 “https:/银行地址/servlet/ICBCINBSEBusinessServlet”，银行来处理 B2C 指令的资金支付；接收通知：如果商户需要银行实时发送交易结果，则需要在订单的通知类型notifyType 设置成“HS” ，并设置有效的接收银行通知的接收地址merURL 字段，银行在支付处理完成后会向此地址 post 交易结果表单，表单数据项已在【

26、B2C 通知商户交易结果接口定义】中说明；商户接收到银行通知后，需使用开发 API 和银行公钥来验证银行签名，以确保通知消息的有效性，以下简要说明验证步骤：1、 商户收到银行通知，即接收到【B2C 通知商户交易结果接口定义】中说明的各字段；各字段使用 URLencode， 如果商户端 web 服务器没有自动将各字段进行URLdecode， 则商户程序需手工进行 URL 解码；2、 获得各字段取值后，根据【通知消息银行签名数据signMsg 格式】格式中说明的数据项和顺序，拼成银行端签名数据明文；3、 使用商户开发 API 和银行公钥文件对表单中的银行签名signMsg 进行验签；4、 验签成功

27、后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关键信息和自己记录的是否一致；5、 商户根据交易结果 tranStat来更新自己的指令状态和相关数据库信息；6、 如果商户没有信息返回给银行则直接关闭此连接； 如果商户需要提供客户取货地址或者希望客户到商户自己的确认页面，则需要返回取货地址或确认页面的 URL 给银行，银行将在显示给客户的交易结果页面显示此URL 的链接供客户点击；五、样例：五、样例：商户提交订单商户提交订单 formform1、订单只能使用 POST 方式提交；使用 https 协议通讯；2、接收 servlet 名称固定为：/servlet/ICBCINBS

28、EBusinessServlet3、银行地址：如果是生产则为“” ，若为模拟测试环境则为“”接口名称固定为“ICBC_PERBANK_B2C”接口版本目前为“1.0.0.0”订单号商户端产生，一天内不能重复。金额以分为单位币种目前只支持人民币，代码为“001”银行提供银行提供“1”判断该客户是否与商户联名；取值“0”不检验客户是否与商户联名。HS 方式实时发送通知；AG 方式不发送通知；接收银行通知地址，目前只支持http 协议 80 端口对于 HS 方式“0” ：发送成功或者失败信息； “1” ，只发送交易成功信息。14 位时间戳商户签名数据 BASE64 编码商户证书公钥 BASE64 编

29、码金额以分为单位以上五个字段用于客户支付页面显示备注字段备注字段注意商户提交订单数据不能提交接口中没有定义的字段，提交按钮不能设置name 属性，如果设置了，提交按钮的值将作为一个变量提交，可能造成数据检查错误。银行通知银行通知 httphttp 报文：报文：（此样例为银行通知消息的 http 报文的数据内容部分，省略 http 报头）interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&orderid=000000001&TranSerialNo=&amount=100&curType=001&merID=0200EC20000012

30、&merAcct=0200029109000030106&verifyJoinFlag=0&JoinFlag=&UserNum=&resultType=0&orderDate=20050801192556¬ifyDate=20050824165910&tranStat=2&comment=failure%2CError_code%3A32147ErrorMsg%3A%CC%E1%BD%BB%D6%A7%B8%B6%B1%ED%B5%A5%CA%B1%BC%E4%CA%FD%BE%DD%B2%BB%D4%DA%D3%D0%D0%A7%CA%B1%BC%E4%B7%B6%CE%A7%A1%A

31、3&remark1=&remark2=&signMsg=Yp4CVHY5rHtcQ9kOxHc70k1PKgpv1jXk0LZgSH0O%2BiEcFA3KKxBRjAhvCvV0hDc9X0WXswMfcGuaKMoCJSMHmdq3lVTYr2hfT1%2FK3nPI6IdCGmo4wJWha8ha4ujyLkQFa36f%2B7C1g9keBro59GPIBHHaRs1Ggmnb2aNimdMAAiM%3D对于每个字段的值都进行URLEncode 编码， 对于 signMsg 字段的银行签名是先对银行签名进行 BASE64 编码后再做的 URLEncode 编码；商户返回取货地址报文：商

32、户返回取货地址报文：如果交易成功后商户需要提供取货地址或希望客户跳转到自己的确认页面， 则在接到银行通知消息后需要返回取货地址或商户确认页面的URL 给银行，银行将在银行的交易结果页面显示此地址的链接。提示：1、 商户返回实质上只是一个内容为 URL 的字符串，不能有任何多余的东西，包括不能有任何的 html 的标签；类似以下 http 回应HTTP/1.1 200 OKServer: Apache/1.39Content-Length: 22Content-type: text/htmlhttp:/4、 此 URL 可以通过 “？” 来挂参数； 举例： http:/merW 的链接，客户点击此链接后，挂的参数将以 GET 方式提交商户。