B2C网银支付商户端接口说明(201104).doc

第1章 对B2C标准商户接口规约1.1 通讯协议目前网银系统支持三种方式与商户之间传递信息： 通过客户浏览器间接通讯：a. 商户引导客户浏览器，将信息提交到网银系统，商户系统发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。商户发送网上银行支付订单、商户发送手机银行支付订单、商户发送家居银行支付订单接口采用该方式通讯。表单数据中需包含商户对订单信息的签名。b. 银行系统引导客户浏览器将信息提交到商户系统。银行反馈订单支付结果（页面通知）接口采用该通讯方式。表单信息中包含银行系统的签名数据。 商户操作员通过浏览器操作网银：商户操作员登录网银操作网银功能，用来提交批量退货文件，下载批量退货反馈文件、业务对账文件与清算对账文件。（网银系统提供的其他商户操作员功能如订单查询等由于不涉及系统之间的接口规范，因此不再描述） 直接通讯：商户系统与银行系统之间直接建立通讯链路，该通讯采用HTTPS协议。a. 由商户系统主动发起通讯，商户系统发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。商户查询订单信息、商户发送B2C退款指令接口采用此通讯方式。表单数据中需包含商户对交易信息的签名。b. 由银行系统主动发起通讯，银行系统为保证商户收到订单支付处理结果，采用主动通知方式向商户发送B2C支付结果。银行网关发往商户系统的指令以POST方式发送，并且使用UTF8编码格式。银行系统向订单中接收通知的商户URL发送支付结果信息。通知信息中包含银行系统的签名数据。1.2 接口报文1.2.1 商户发送网上银行支付订单接口名称：RecvOrder.do接口说明：客户在商户网站确认进行订单支付，选择中行网上银行支付后，商户系统负责按此数据规格将消费交易信息发往中行支付网关系统；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明1.商户号merchantNoX(20)必填BOC商户ID2.支付类型payTypeX(10)必填商户支付服务类型1：网上购物3.商户订单号orderNoX(19)必填商户系统产生的订单号4.订单币种curCodeX(3)必填目前只支持001：人民币固定填0015.订单金额orderAmountX(13)必填格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.106.订单时间orderTime9(14)必填格式：YYYYMMDDHHMISS其中时间为24小时格式，例:2010年3月2日下午4点5分28秒表示为201003021605287.订单说明orderNoteX(200)必填订单描述，要求如果全中文最多允许60个汉字长度8.商户接收通知URLorderUrlX(100)必填客户支付完成后银行向商户发送支付结果，商户系统负责接收银行通知的URL9.超时时间orderTimeoutDate9(14)选填（一般商户无需上送，仅当商户需指定支付截止时间时上送。）格式：YYYYMMDDHHMISS其中时间为24小时格式，例:2010年3月2日下午4点5分28秒表示为20100302160528。其含义为：如客户在该时间点仍未确认支付，则该笔支付将超时失败。10.商户签名数据signDataX(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户订单号|订单时间|订单币种|订单金额|商户号orderNo|orderTime|curCode|orderAmount|merchantNo接口示例：= B2C商户端接口-发送网上银行支付订单:RecvOrder.do =1.2.2 商户发送手机银行支付订单接口名称：B2CMobileRecvOrder.do接口说明：客户在商户手机WAP网站确认进行订单支付，选择中行手机银行支付后，商户系统负责按此数据规格将消费交易信息发往中行支付网关系统；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明1.商户号merchantNoX(20)必填BOC商户ID2.支付类型payTypeX(10)必填商户支付服务类型1：网上购物3.商户订单号orderNoX(19)必填商户系统产生的订单号4.订单币种curCodeX(3)必填目前只支持001：人民币固定填0015.订单金额orderAmountX(13)必填格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.106.订单时间orderTime9(14)必填格式：YYYYMMDDHHMISS其中时间为24小时格式，例:2010年3月2日下午4点5分28秒表示为201003021605287.订单说明orderNoteX(200)必填订单描述，要求如果全中文最多允许60个汉字长度8.商户接收通知URLorderUrlX(100)必填客户支付完成后银行向商户发送支付结果，商户系统负责接收银行通知的URL9.WAP客户标识spMobileX(54)选填如果客户通过商户系统直接发订单到中行网关，该域可空；如果客户通过中行手机商城的链接到商户时，中行手机商城会生成由渠道号和手机号组合加密的数据传送给WAP商户系统，客户在WAP商户系统对订单进行支付时，WAP商户系统需要提供该信息；10.超时时间orderTimeoutDate9(14)选填（一般商户无需上送，仅当商户需指定支付截止时间时上送。）格式：YYYYMMDDHHMISS其中时间为24小时格式，例:2010年3月2日下午4点5分28秒表示为20100302160528。其含义为：如客户在该时间点仍未确认支付，则该笔支付将超时失败。11.商户签名数据signDataX(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户订单号|订单时间|订单币种|订单金额|商户号orderNo|orderTime|curCode|orderAmount|merchantNo接口示例：= B2C商户端接口-发送手机银行支付订单:B2CMobileRecvOrder.do = 1.2.3 商户发送家居银行支付订单接口名称：HomeBankRecvOrder.do接口说明：客户在商户电视机顶盒系统界面确认进行订单支付，选择中行家居银行支付后，商户系统负责按此数据规格将消费交易信息发往中行支付网关系统；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明1.商户号merchantNoX(20)必填BOC商户ID2.支付类型payTypeX(10)必填商户支付服务类型1：网上购物3.商户订单号orderNoX(19)必填商户系统产生的订单号4.订单币种curCodeX(3)必填目前只支持001：人民币固定填0015.订单金额orderAmountX(13)必填格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.106.订单时间orderTime9(14)必填格式：YYYYMMDDHHMISS其中时间为24小时格式，例:2010年3月2日下午4点5分28秒表示为201003021605287.订单说明orderNoteX(200)必填订单描述，要求如果全中文最多允许60个汉字长度8.商户接收通知URLorderUrlX(100)必填客户支付完成后银行向商户发送支付结果，商户系统负责接收银行通知的URL9.超时时间orderTimeoutDate9(14)选填（一般商户无需上送，仅当商户需指定支付截止时间时上送。）格式：YYYYMMDDHHMISS其中时间为24小时格式，例:2010年3月2日下午4点5分28秒表示为20100302160528。其含义为：如客户在该时间点仍未确认支付，则该笔支付将超时失败。10.商户签名数据signDataX(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户订单号|订单时间|订单币种|订单金额|商户号orderNo|orderTime|curCode|orderAmount|merchantNo接口示例：= B2C商户端接口-发送家居银行支付订单:HomeBankRecvOrder.do = 1.2.4 银行反馈订单支付结果(页面通知)接口说明：中行支付网关接收商户发来的网上银行支付订单、手机银行支付订单或家居银行支付订单后，引导客户进行支付确认，客户通过中行网银、手机银行或家居银行提交支付指令后，支付网关进行支付处理，处理完成后由网上银行支付结果页面、手机银行支付结果页面或家居银行支付结果页面向商户系统按以下数据规格反馈订单支付结果；指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：序号名称字段最大长度说明1.商户号merchantNoX(20)BOC商户ID2.商户订单号orderNoX(19)商户系统产生的订单号3.银行订单流水号orderSeq9(20)银行的订单流水号（银行产生的订单唯一标识）4.银行卡类别cardTypX(2)01：中行借记卡02：中行信用卡，信用卡（分行卡）04：中行信用卡，信用卡（总行卡）11：银联借记卡21：VISA借记卡22：VISA信用卡31：MC 借记卡32：MC 信用卡42：运通卡52：大来卡62：JCB卡5.支付时间payTime9(14)格式：YYYYMMDDHHMISS6.订单状态orderStatusX(2)0：未处理1：支付2：撤销3：退货4：未明5：失败7.支付金额payAmountX(13)格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.108.支付卡号acctNoX(19)为保护个人客户信息，我行暂不提供该数据项，以*反馈9.持卡人姓名holderNameX(30)为保护个人客户信息，我行暂不提供该数据项，以*反馈10.支付卡省行联行号ibknumX(5)为保护个人客户信息，我行暂不提供该数据项，以*反馈11.客户支付IP地址orderIpX(40)客户通过网银支付时的IP地址信息格式：n.n.n.n其中n为0-255的数字例如：12.客户浏览器Refer信息orderReferX(200)客户浏览器跳转至网银支付登录界面前所在页面的URL（urlEncode格式）13.银行交易流水号bankTranSeqX(22)银行交易日期(8位)+POS终端号(8位)+POS流水号(6位)14.返回操作类型returnActFlagX(1)1：支付结果通知2：电话订单结果通知3：退款结果通知4：订单查询结果15.电话号码phoneNumX(50)电话支付时使用的电话号码16.中行签名数据signDataX(4000)必填中行签名数据串格式，各项数据用管道符分隔：商户号|商户订单号|银行订单流水号|银行卡类别|支付时间|订单状态|支付金额 merchantNo|orderNo|orderSeq|cardTyp|payTime|orderStatus|payAmount1.2.5 银行发送B2C支付结果通知(主动通知)例子：参数部分可参考Para Info 部分We receive a 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-merchantNo=104330183980005orderNo=zsc1orderSeq=69916502cardTyp=12payTime=20100627000000orderStatus=1payAmount=0.01orderIp=0orderRefer=http%3A%2F%2Flocalhost%2FB2C.htmlbankTranSeq=2010062733011575000001returnActFlag=1phoneNum=signData=MIIEZgYJKoZu3ukpfzDOJ8onjJl+gUxoP1FcWqQqlhzoQHzH6z4J2nEyGqDI+jfgdnMpqp59wgkLZ5ibUV8QgiqWqLTVYWVssIJbPDmpJ1L2BpXgVheJvqhrVnbrVgy+Vg2/vEJ00cABUcegcJm28VHdpbM=参考银行反馈订单支付结果(页面通知)B2C订单支付成功的银行主动通知示例：例子：参数部分可参考Para Info 部分We receive a 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-merchantNo=104330183980005orderNo=zsc2orderSeq=69916503cardTyp=12payTime=20100627000000orderStatus=5payAmount=0.02orderIp=0orderRefer=http%3A%2F%2Flocalhost%2FB2C.htmlbankTranSeq=2010062733011575000001returnActFlag=1phoneNum=signData=MIIEZgYJKoZu3ukpfzDOJ8onjJl+gUxoP1FcWqQqlhzoQHzH6z4J2nEyGqDI+jfgdnMpqp59wgkLZ5ibUV8QgiqWqLTVYWVssIJbPDmpJ1L2BpXgVheJvqhrVnbrVgy+Vg2/vEJ00cABUcegcJm28VHdpbM=B2C订单支付失败的银行主动通知示例：1.2.6 商户发送查询订单请求商户通过https指令向中行支付网关请求查询指定订单的支付情况。商户系统需要参照以下数据规格构造https订单支付情况查询指令。请求入口：CommonQueryOrder.do序号名称字段最大长度说明1.商户号merchantNoX(20)BOC商户ID2.商户订单号字符串orderNosX(1000)商户系统产生的订单号，支持输入多个订单号进行查询，最多支持50个订单号的查询格式：orderNo|orderNo|orderNo例如：4|11|10|12|133.商户签名信息signDataX(4000)商户签名数据串格式，各项数据用冒号分隔（其中多笔订单号使用管道符分隔）：商户号:商户订单号字符串merchantNo:orderNos接口示例：= 理财直付商户端接口商户发送查询订单请求 CommonQueryOrder.do =中行以XML方式按照以下数据规格向商户系统进行反馈:序号报文要素属性类型备注1.Message root1.12.BusinessHeader业务头报文块1.13.-MessageId 报文标识号1.14.-HandleStatus 处理状态1.1A|B|KA-成功 B-失败 K-未明5.-BodyFlag 业务体报文块存在标识1.10|10-有包体 1-无包体6.-ReturnCode 报文处理返回码0.17.BusinessBody业务体报文块0.n8.-商户号1.1X(20)BOC商户ID9.-商户订单号1.1X(19)商户系统产生的订单号10.-银行订单流水号1.19(20)银行的订单流水号（银行产生的订单唯一标识）11.-订单状态1.1X(2)订单状态：0-未处理1-支付4-未明5-失败12.-银行卡类别1.1X(2)银行卡类别：01：中行借记卡02：中行信用卡，信用卡（分行卡）04：中行信用卡，信用卡（总行卡）11：银联借记卡21：VISA借记卡22：VISA信用卡31：MC 借记卡32：MC 信用卡42：运通卡52：大来卡62：JCB卡13.-支付卡号1.1X(18)为保护个人客户信息，我行暂不提供该数据项，以*反馈14.-持卡人姓名1.1X(30)为保护个人客户信息，我行暂不提供该数据项，以*反馈15.-支付卡省行联行号1.1X(5)为保护个人客户信息，我行暂不提供该数据项，以*反馈16.-支付时间1.19(14)支付交易的日期时间格式：YYYYMMDDHHMISS17.-支付金额1.1X(13)支付金额，格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.1018.-访问者IP1.1X(40)客户通过网银支付时的IP地址信息格式：n.n.n.n其中n为0-255的数字例如：19.-访问者Refer信息1.1X(3000)客户浏览器跳转至网银支付登录界面前所在页面的URL（urlEncode格式）接口示例：银行返回数据示例（返回订单信息）： 0000204 A 0 333555 1225 12851 0 1 5555510100123456789 张三 0742820110624171313 14.00 333555 1226 12112 0 1 5555510100123456789 张三 0742820110624171313 100.00 1.2.7 商户发送B2C退款指令接口名称：RefundOrder.do接口说明：客户与商户协商退货后，商户系统对原来已经支付成功的订单（包括网上银行支付订单、手机银行支付订单、家居银行支付订单）进行退款时，商户系统采用HTTPS协议按此数据规格将B2C退款交易信息发往中行支付网关系统，银行完成退款处理后向商户实时反馈处理结果；商户主动发往银行网关的指令均以POST方式发送，并且使用UTF8编码格式。数据项说明：商户按照以下数据规格向中行支付网关提交单笔B2C联机退款指令。序号名称字段最大长度说明1.商户号merchantNoX(20)必填BOC商户ID2.商户退款交易流水号mRefundSeqX(30)必填商户系统产生的交易流水号3.退款币种curCodeX(3)必填目前只支持001：人民币固定填0014.退款金额refundAmountX(13)必填退款金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.105.商户订单号orderNoX(19)必填商户系统产生的订单号，原支付订单的商户订单号6.商户签名数据signDataX(4000)必填商户签名数据串格式，各项数据用管道符分隔：商户号|商户退款交易流水号|退款币种|退款金额|商户订单号merchantNo | mRefundSeq | curCode | refundAmount |orderNo 中行支付网关进行B2C退款处理完成后向商户系统按以下数据规格同步反馈退款处理结果（注意：处理状态为成功时一定存在包体数据记录退款交易信息；处理状态为失败时有两种情况，一种是无包体数据表示商户提交的数据校验不通过；另一种是有包体数据表示银行后台系统因为卡状态异常等原因进行退款处理失败）。序号名称字段最大长度说明Header报文头1.商户号merchantNoX(20)BOC商户ID2.返回操作类型returnActFlagX(1)银行返回的操作类型（该交易结果返回为3）1：支付结果通知2：电话订单结果通知3：退款结果通知4：订单查询结果3.处理状态dealStatusX(1)银行联机退款的处理状态（铁道部商户只有0、1两个状态）0：成功1：失败2：未明4.包体标志bodyFlagX(1)是否有包体数据0：有包体数据1：无包体数据5.错误码exceptionX(10)失败错误码处理状态dealStatus为成功时，该域为空；处理状态dealStatus为失败时，该域为具体的错误代码Body报文体1.商户退款交易流水号mRefundSeqX(30)商户系统产生的交易流水号2.币种curCodeX(3)目前只支持001：人民币3.退款金额refundAmountX(13)退款金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.104.商户订单号orderNoX(19)商户系统产生的订单号，原支付订单的商户订单号5.银行订单流水号orderSeq9(20)银行的订单流水号（银行产生的订单唯一标识）6.订单金额orderAmountX(13)订单金额格式：整数位不前补零,小数位补齐2位即：不超过10位整数位+1位小数点+2位小数无效格式如123，.10，1.1,有效格式如1.00，0.107.银行交易流水号bankTranSeqX(22)银行交易流水号