中国银行网上支付B2C商户端接口说明.doc

资源描述

《中国银行网上支付B2C商户端接口说明.doc》由会员分享，可在线阅读，更多相关《中国银行网上支付B2C商户端接口说明.doc（37页珍藏版）》请在三一文库上搜索。

1、网上支付接口说明中国银行网上支付B2C商户端接口说明- PaymentGateway Interface Specification单位电子渠道开发部（网银团队）撰写人曹克、孙永、延冰、陈卫强、梁栋版本V2.3序号修改人日期修改说明1曹克2008.10.28创建文档，编写文档提纲。2陈卫强2008.10.29添加接口报文章节内容3孙永2008.10.29添加安全章节内容4曹克2008.10.30添加前言，补充及通讯协议章节，修改文档格式5延冰2009.12.281、在2.2.1商户发送支付指令中增加WAP商户系统发送订单指令的指令参考6延冰2009.12.291、增加银行主动通知接口：网关发

2、送B2C支付结果通知7延冰2010.01.281、在2.3.2签名与验签一节中增加商户验证银行数字签名异常后的处理8延冰2010.04.151、在指令说明中增加：商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式9延冰2010.08.301、修改2.2.1商户发送支付指令接口名称为商户发送网银支付订单；增加2.2.2商户发送手机银行支付订单；修改2.2.2 支付结果反馈接口为银行反馈订单支付结果；修改2.2.3 支付状态查询接口为商户查询订单信息；修改2.2.8 网关发送B2C支付结果通知为银行发送B2C支付结果通知；2、支付结果反馈接口返回项增加：客户支

3、付IP、客户浏览器Refer、银行交易流水号、返回操作类型；3、增加联机退款接口：商户发送B2C退款指令；4、网关发送B2C支付结果通知中增加：客户支付IP、客户浏览器Refer、银行交易流水号、返回操作类型；5、在附件3.1中增加商户批量退货文件示例；6、增加附件3.2错误码说明；第 37 页1前言51.1文档说明51.1.1编写目的51.1.2参考资料51.2适用读者52接口规约62.1通讯协议62.2接口报文82.2.1商户发送网银支付订单82.2.2商户发送手机银行支付订单102.2.3银行反馈订单支付结果132.2.4银行发送B2C支付结果通知152.2.5商户查询订单信息192.2

4、.6商户发送B2C退款指令232.2.7批量退货及反馈文件格式282.2.8业务对账文件格式302.2.9清算对账文件格式312.3安全机制332.3.1安全机制简介332.3.2签名与验签333附件363.1批量文件接口示例文件363.2错误码说明361 前言1.1 文档说明本文描述了中国银行网上支付相关服务通讯协议、报文格式、安全机制。作为商户端系统技术人员开发的参考文档。1.1.1 编写目的为使商户端系统开发人员了解网上支付服务的相关通讯接口细节。1.1.2 参考资料中国银行网上支付相关的业务流程见商户端开发指引。本文不再复述。1.2 适用读者商户端系统开发人员（分析师、设计人员、程序员

5、）。2 接口规约2.1 通讯协议目前网银系统支持三种方式与商户之间传递信息：通过客户浏览器间接通讯：a. 商户引导客户浏览器，将信息提交到网银系统，商户系统发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。商户发送支付指令接口采用该方式通讯。表单数据中需包含商户对订单信息的签名。b. 网银引导客户浏览器将信息提交到商户系统。银行反馈订单支付结果接口采用该通讯方式。表单数据中包含网银系统的签名信息。商户操作员通过浏览器操作网银：商户操作员登录网银操作网银功能，用来提交批量退货文件，下载业务对账文件与清算对账文件。（网银系统提供的其他商户操作员功能如状态查询等由于不涉及系统之间

6、的接口规范，因此不再描述）直接通讯：商户系统与网银系统之间直接建立通讯链路，商户系统采用HTTPS协议主动发起通讯，商户系统发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。商户查询订单信息、商户发送B2C退款指令接口采用此通讯方式。银行系统为保证商户收到订单支付处理结果，采用主动通知方式向商户发送B2C支付结果，银行系统采用POST方式向订单中接收通知的商户URL发送支付结果信息。2.2 接口报文2.2.1 商户发送网银支付订单接口名称：RecvOrder.do接口说明：客户在商户网站确认进行订单支付，选择中行网上银行支付后，商户系统负责按此数据规格将消费交易信息发往中行支

7、付网关系统；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明01商户号merchantNoX(20)必填BOC商户ID02支付类型payTypeX(10)必填商户支付服务类型1：网上购物2：基金直销03商户订单号orderNoX(19)必填商户系统产生的订单号04订单币种curCodeX(3)必填目前只支持001：人民币固定填00105订单金额orderAmountX(13)必填格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1006订单时间o

9、er.do =2.2.2 商户发送手机银行支付订单接口名称：B2CMobileRecvOrder.do接口说明：客户在商户手机WAP网站确认进行订单支付，选择中行手机银行支付后，商户系统负责按此数据规格将消费交易信息发往中行支付网关系统；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明01商户号merchantNoX(20)必填BOC商户ID02支付类型payTypeX(10)必填商户支付服务类型1：网上购物2：基金直销03商户订单号orderNoX(19)必填商户系统产生的订单号04订单币种curCodeX(3)必填目前只支持00

10、1：人民币固定填00105订单金额orderAmountX(13)必填格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1006订单时间orderTime9(14)必填格式：YYYYMMDD24HHMMSS其中时间为24小时格式，如下午3点15表示为15150007订单说明orderNoteX(30)必填订单描述08商户接收通知URLorderUrlX(100)必填客户支付完成后银行向商户发送支付结果，商户系统负责接收银行通知的URL09WAP客户标识spMobileX(54)选填如果客户通过商户系统直接发

12、接收商户发来的订单后按照客户支付请求进行支付处理，处理完成后在银行支付结果界面向商户系统按以下数据规格反馈支付结果；指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明01商户号merchantNoX(20)BOC商户ID02商户订单号orderNoX(19)商户系统产生的订单号03银行订单流水号orderSeq9(20)银行的订单流水号（银行产生的订单唯一标识）04银行卡类别cardTypX(2)银行卡类别：01：中行借记卡02：中行信用卡，信用卡（分行卡）04：中行信用卡，信用卡（总行卡）11：银联借记卡21：VISA借记卡22：VISA信用卡31：MC

13、借记卡32：MC 信用卡42：运通卡52：大来卡62：JCB卡05支付时间payTime9(14)支付交易的日期时间格式：YYYYMMDD24HHMMSS06订单状态orderStatusX(2)订单状态：0：未处理1：支付2：撤销3：退货4：未明5：失败07支付金额payAmountX(13)支付金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1008客户支付IP地址orderIpX(40)客户通过网银支付时的IP地址信息格式：n.n.n.n其中n为0-255的数字例如：192.168.0.109

15、o|orderSeq|cardTyp|payTime|orderStatus|payAmount2.2.4 银行发送B2C支付结果通知接口名称：无接口说明：为避免银行支付界面反馈支付结果失效，中行支付网关按此数据规格将B2C订单支付结果主动通过HTTP或HTTPS方式POST发往商户系统。参数的编码方式使用UTF-8编码后，再用application/x-www-form-urlencoded方式转译后发出。数据项说明：序号名称字段最大长度说明01商户号merchantNoX(20)BOC商户ID02商户订单号orderNoX(30)商户系统产生的订单号03银行订单流水号orderSeq9(2

16、0)银行的订单流水号（银行产生的订单唯一标识）04银行卡类别cardTypX(2)银行卡类别：01：中行借记卡02：中行信用卡，信用卡（分行卡）04：中行信用卡，信用卡（总行卡）11：银联借记卡21：VISA借记卡22：VISA信用卡31：MC 借记卡32：MC 信用卡42：运通卡52：大来卡62：JCB卡05支付时间payTime9(14)支付交易的日期时间格式：YYYYMMDD24HHMMSS06订单状态orderStatusX(2)订单状态：0：未处理1：支付2：撤销3：退货4：未明5：失败07支付金额payAmountX(13)支付金额格式：整数位不前补零,小数位补齐2位即：不超过10

17、位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1008客户支付IP地址orderIPX(40)客户通过网银支付时的IP地址信息格式：n.n.n.n其中n为0-255的数字例如：192.168.0.109客户浏览器Refer信息orderReferX(200)客户浏览器跳转至网银支付登录界面前所在页面的URL（urlEncode格式）10银行交易流水号bankTranSeqX(22)银行交易流水号银行交易日期(8位)+POS终端号(8位)+POS流水号(6位)11返回操作类型returnActFlagX(1)银行返回的操作类型1：支付结果通知2：电话订单

19、:8080accept=text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2connection=keep-alivecontent-type=application/x-www-form-urlencodedcontent-length=1969-para info-orderSeq=69916502signData=MIIEZgYJKoZu3ukpfzDOJ8onjJl+gUxoP1FcWqQqlhzoQHzH6z4J2nEyGqDI+jfgdnMpqp59wgkLZ5ibUV8QgiqWqLTVYWVssIJbPDmpJ1L2BpXgV

20、heJvqhrVnbrVgy+Vg2/vEJ00cABUcegcJm28VHdpbM=orderStatus=1payAmount=0.01orderRefer=http%3A%2F%2Flocalhost%2FB2C.htmlpayTime=20100627000000merchantNo=104330183980005orderIp=22.11.99.80returnActFlag=1cardTyp=12bankTranSeq=2010062733011575000001phoneNum=orderNo=zsc1B2C订单支付失败的银行主动通知示例：例子：参数部分可参考Para Info

21、部分We receive a post method request !-header info-user-agent=Java/1.5.0host=22.11.99.80:8080accept=text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2connection=keep-alivecontent-type=application/x-www-form-urlencodedcontent-length=1969-para info-orderSeq=69916503signData=MIIEZgYJKoZu3ukpfzDOJ8onjJl

22、+gUxoP1FcWqQqlhzoQHzH6z4J2nEyGqDI+jfgdnMpqp59wgkLZ5ibUV8QgiqWqLTVYWVssIJbPDmpJ1L2BpXgVheJvqhrVnbrVgy+Vg2/vEJ00cABUcegcJm28VHdpbM=orderStatus=5payAmount=0.02orderRefer=http%3A%2F%2Flocalhost%2FB2C.htmlpayTime=20100627000000merchantNo=104330183980005orderIp=22.11.99.80returnActFlag=1cardTyp=12bankTran

23、Seq=2010062733011575000001phoneNum=orderNo=zsc22.2.5 商户查询订单信息接口名称：QueryOrder.do接口说明：商户系统采用HTTPS协议向中行支付网关请求查询指定订单的支付情况。商户系统需要参照以下数据规格构造https订单支付情况查询指令，银行按照条件将能够查询到的所有订单信息实时返回给商户系统（注意多笔订单查询时银行只返回能够查询到的订单信息）；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：商户按照以下数据规格向中行支付网关查询指定订单的支付状态。序号名称字段最大长度说明01商户号mercha

24、ntNoX(20)BOC商户ID02商户订单号字符串orderNosX(1000)商户系统产生的订单号，支持输入多个订单号进行查询，最多支持50个订单号的查询格式：orderNo|orderNo|orderNo例如：4|11|10|12|1303商户签名信息signDataX(4000)商户签名数据串格式，各项数据用冒号分隔（其中多笔订单号使用管道符分隔）：商户号:商户订单号字符串merchantNo:orderNos中行支付网关按照指定订单号查询订单的支付状态，按照以下XML数据规格向商户系统进行反馈。序号名称字段最大长度说明Header报文头01商户号merchantNoX(20)BOC商

25、户ID02错误码exceptionX(10)失败错误码处理成功时无此域；处理失败时，该域为具体的错误代码Body报文体01商户订单号orderNoX(19)商户系统产生的订单号02银行订单流水号orderSeq9(20)银行的订单流水号（银行产生的订单唯一标识）03订单状态orderStatusX(2)订单状态：0：未处理1：支付2：撤销3：退货4：未明5：失败04银行卡类别cardTypX(2)银行卡类别：01：中行借记卡02：中行信用卡，信用卡（分行卡）04：中行信用卡，信用卡（总行卡）11：银联借记卡21：VISA借记卡22：VISA信用卡31：MC 借记卡32：MC 信用卡42：运通卡

26、52：大来卡62：JCB卡05支付时间payTime9(14)支付交易的日期时间格式：YYYYMMDD24HHMMSS06支付金额payAmountX(13)支付金额，格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.10接口示例：商户上送数据示例：= B2C商户端接口-查询订单信息:QueryOrder.do =银行返回数据示例（返回订单信息）： 104110041000000 TEST0001 1001 1 04 20090605000000 200.12 TEST0009 1009 1 04 2009

27、0609121212 360.00 银行返回数据示例（未查询到任何订单信息）： 104110041000000 银行返回数据示例（上送信息有误）： 104110041000000 merchant is not existed 2.2.6 商户发送B2C退款指令接口名称：RefundOrder.do接口说明：客户与商户协商退货后，商户系统对原来已经支付成功的订单（包括网银支付订单、手机银行支付订单）进行退款时，商户系统采用HTTPS协议按此数据规格将B2C退款交易信息发往中行支付网关系统，银行完成退款处理后向商户实时反馈处理结果；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8

28、编码格式。数据项说明：商户按照以下数据规格向中行支付网关提交单笔B2C联机退款指令。序号名称字段最大长度说明01商户号merchantNoX(20)必填BOC商户ID02商户退款交易流水号mRefundSeqX(30)必填商户系统产生的交易流水号03退款币种curCodeX(3)必填目前只支持001：人民币固定填00104退款金额refundAmountX(13)必填退款金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1005商户订单号orderNoX(19)必填商户系统产生的订单号，原支付订单的商户

展开阅读全文