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

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、增加银行主动通知接口：网关发送b2c支付结果通

2、知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、支付结果反馈接口返回项增加：客户支付ip、客户浏览器

3、refer、银行交易流水号、返回操作类型；3、增加联机退款接口：商户发送b2c退款指令；4、网关发送b2c支付结果通知中增加：客户支付ip、客户浏览器refer、银行交易流水号、返回操作类型；5、在附件3.1中增加商户批量退货文件示例；6、增加附件3.2错误码说明；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.6商户发送b2c退款指令23

4、2.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 适用读者商户端系统开发人员（分析师、设计人员、程序员）。2 接口规约2.1 通讯协

5、议目前网银系统支持三种方式与商户之间传递信息： 通过客户浏览器间接通讯：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订单时间ordertime9(14)必填

8、格式：yyyymmdd24hhmmss其中时间为24小时格式，如下午3点15表示为15150007订单说明ordernotex(30)必填订单描述08商户接收通知urlorderurlx(100)必填客户支付完成后银行向商户发送支付结果，商户系统负责接收银行通知的url09商户签名数据signdatax(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户订单号|订单时间|订单币种|订单金额|商户号orderno|ordertime|curcode|orderamount|merchantno接口示例：= b2c商户端接口-发送网银支付订单:recvorder.do =2.2.2 商户

9、发送手机银行支付订单接口名称：b2cmobilerecvorder.do接口说明：客户在商户手机wap网站确认进行订单支付，选择中行手机银行支付后，商户系统负责按此数据规格将消费交易信息发往中行支付网关系统；商户主动发往银行网关的指令均以post方式发送，并且使用utf8编码格式。数据项说明：序号名称字段最大长度说明01商户号merchantnox(20)必填boc商户id02支付类型paytypex(10)必填商户支付服务类型1：网上购物2：基金直销03商户订单号ordernox(19)必填商户系统产生的订单号04订单币种curcodex(3)必填目前只支持001：人民币固定填00105订单

10、金额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)选填如果客户通过商户系统直接发订单到中行网关，该域可空；如果

11、客户通过中行手机商城的链接到商户时，中行手机商城会生成由渠道号和手机号组合加密的数据传送给wap商户系统，客户在wap商户系统对订单进行支付时，wap商户系统需要提供该信息；10商户签名数据signdatax(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户订单号|订单时间|订单币种|订单金额|商户号orderno|ordertime|curcode|orderamount|merchantno接口示例：= b2c商户端接口-发送手机银行支付订单:b2cmobilerecvorder.do = 2.2.3 银行反馈订单支付结果接口名称：无接口说明：银行接收商户发来的订单后按照客户支

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 借记卡32：mc 信用卡42

13、：运通卡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的数字例如：09客户浏览器refer信息ord

14、erreferx(200)客户浏览器跳转至网银支付登录界面前所在页面的url（urlencode格式）10银行交易流水号banktranseqx(22)银行交易流水号银行交易日期(8位)+pos终端号(8位)+pos流水号(6位)11返回操作类型returnactflagx(1)银行返回的操作类型1：支付结果通知2：电话订单结果通知3：退款结果通知4：订单查询结果12网关签名数据signdatax(4000)必填网关签名数据串格式，各项数据用管道符分隔：商户号|商户订单号|银行订单流水号|银行卡类别|支付时间|订单状态|支付金额 merchantno|orderno|orderseq|card

15、typ|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(20)银行的订单流水号（银行产生

16、的订单唯一标识）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位整数位+1位小数点+2位小数

17、无效格式如123，.10，1.1,有效格式如1.00，0.1008客户支付ip地址orderipx(40)客户通过网银支付时的ip地址信息格式：n.n.n.n其中n为0-255的数字例如：09客户浏览器refer信息orderreferx(200)客户浏览器跳转至网银支付登录界面前所在页面的url（urlencode格式）10银行交易流水号banktranseqx(22)银行交易流水号银行交易日期(8位)+pos终端号(8位)+pos流水号(6位)11返回操作类型returnactflagx(1)银行返回的操作类型1：支付结果通知2：电话订单结果通知3：退款结果通知4：订

18、单查询结果12网关签名数据signdatax(4000)必填网关签名数据串格式，各项数据用管道符分隔：商户号|商户订单号|银行订单流水号|银行卡类别|支付时间|订单状态|支付金额 merchantno|orderno|orderseq|cardtyp|paytime|orderstatus|payamount接口示例：b2c订单支付成功的银行主动通知示例：例子：参数部分可参考para info 部分we receive a post method request !-header info-user-agent=java/1.5.0host=0:8080accept=tex

19、t/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+jfgdnmpqp59wgklz5ibuv8qgiqwqltvywvssijbpdmpj1l2bpxgvhejvqhrvnbrvgy+

20、vg2/vej00cabucegcjm28vhdpbm=orderstatus=1payamount=0.01orderrefer=http%3a%2f%2flocalhost%2fb2c.htmlpaytime=20100627000000merchantno=104330183980005orderip=0returnactflag=1cardtyp=12banktranseq=2010062733011575000001phonenum=orderno=zsc1b2c订单支付失败的银行主动通知示例：例子：参数部分可参考para info 部分we receive a

21、post method request !-header info-user-agent=java/1.5.0host=0: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+guxop1fcwqqqlh

22、zoqhzh6z4j2neygqdi+jfgdnmpqp59wgklz5ibuv8qgiqwqltvywvssijbpdmpj1l2bpxgvhejvqhrvnbrvgy+vg2/vej00cabucegcjm28vhdpbm=orderstatus=5payamount=0.02orderrefer=http%3a%2f%2flocalhost%2fb2c.htmlpaytime=20100627000000merchantno=104330183980005orderip=0returnactflag=1cardtyp=12banktranseq=20100627330

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

24、d02商户订单号字符串ordernosx(1000)商户系统产生的订单号，支持输入多个订单号进行查询，最多支持50个订单号的查询格式：orderno|orderno|orderno例如：4|11|10|12|1303商户签名信息signdatax(4000)商户签名数据串格式，各项数据用冒号分隔（其中多笔订单号使用管道符分隔）：商户号:商户订单号字符串merchantno:ordernos中行支付网关按照指定订单号查询订单的支付状态，按照以下xml数据规格向商户系统进行反馈。序号名称字段最大长度说明header报文头01商户号merchantnox(20)boc商户id02错误码excepti

25、onx(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：运通卡52：大来卡62：jcb卡05

26、支付时间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 20090609121212 360.

27、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)必填商户系统产生的订单号，原支付订单的商户订单号06商户签名数据sign

29、datax(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户号|商户退款交易流水号|退款币种|退款金额|商户订单号merchantno | mrefundseq | curcode | refundamount |orderno 中行支付网关进行b2c退款处理完成后向商户系统按以下数据规格同步反馈退款处理结果（注意：处理状态为成功时一定存在包体数据记录退款交易信息；处理状态为失败时有两种情况，一种是无包体数据表示商户提交的数据校验不通过；另一种是有包体数据表示银行后台系统因为卡状态异常等原因进行退款处理失败）。序号名称字段最大长度说明header报文头01商户号merchantno

30、x(20)boc商户id02返回操作类型returnactflagx(1)银行返回的操作类型（该交易结果返回为3）1：支付结果通知2：电话订单结果通知3：退款结果通知4：订单查询结果03处理状态dealstatusx(1)银行联机退款的处理状态0：成功1：失败04包体标志bodyflagx(1)是否有包体数据0：有包体数据1：无包体数据05错误码exceptionx(10)失败错误码处理状态dealstatus为成功时，该域为空；处理状态dealstatus为失败时，该域为具体的错误代码body报文体01商户退款交易流水号mrefundseqx(30)商户系统产生的交易流水号02币种curco

31、dex(3)目前只支持001：人民币03退款金额refundamountx(13)退款金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1004商户订单号ordernox(19)商户系统产生的订单号，原支付订单的商户订单号05银行订单流水号orderseq9(20)银行的订单流水号（银行产生的订单唯一标识）06订单金额orderamountx(13)订单金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1007银

32、行交易流水号banktranseqx(22)银行交易流水号银行交易日期(8位)+pos终端号(8位)+pos流水号(6位)08银行交易时间trantime9(14)退款交易处理的日期时间格式：yyyymmdd24hhmmss09网关签名数据signdatax(4000)网关签名数据串格式，各项数据用管道符分隔：商户号|商户退款交易流水号|退款金额|商户订单号|银行订单流水号|订单金额|银行交易流水号|银行交易时间|退款处理状态merchantno|mrefundseq|refundamount|orderno|orderseq|orderamount| banktranseq |trantim

33、e|dealstatus接口示例：商户上送数据示例：= b2c商户端接口-发送b2c退款指令:refundorder.do =银行返回数据示例（退款处理成功）： 104110041000000 3 0 0 r0001 001 180.00 324322 1231 200.12 2010010111111111123456 20090605000000 miiezgyjkozihvcnaqccoiievzccbfmcaqmxctahbgurdgmcgjalbgkqhkig9w0bbwggggmdmiidgtccagggawibagiqibay5mfnk0lhzcajtcsdezanbgkqhki

34、g9w0baqufadbdmqswcqydvqqgewjdtjewmbqga1uechmnqkfosybpribdseloqteqma4ga1uecbmhqkvjsklorzeqma43pv58b8im= 银行返回数据示例（退款处理失败）： 104110041000000 3 1 1 e00000014 2.2.7 批量退货及反馈文件格式 商户提供的批量退货文件：文件商户批量退货文件说明商户通过网银等前端渠道系统向中行支付网关提交的批量退货文件。1文件格式必须为txt文本文件 2文本文件最多包含5000笔退货指令3文件内容每行必须符合标准格式，且每行必须以回车换行结束4数据项之间必须以管道符“|”分隔5如数据项为空时，则相应的数据项不需填任何信息（包括空格）6标准格式：银行订单流水号|商户号|订单号|订单