网上银行系统C2C信用支付接口商户手册(09年2月版).doc

网上银行商户手册 C2C信用支付接口商户手册中国工商银行软件开发中心Copyright Reserved1. 文档属性文档属性内容文档名称：网上银行系统C2C信用支付接口商户手册文档版本号：1.1文档状态：正式稿文档编写完成日期2007-7-122. 文档变更历史清单文档版本号变更日期修改人变更内容简述112007-7-12曾凯增加描述xml头；通知消息方式；1.112009-1-21魏阁麟修改2.4节“要延长的有效期长度”字段的描述说明第 1 章业务说明3第 2 章商户接口52.1买家预支付62.1买家提前支付102.1超期商户支付122.4商户延期支付到期日132.5买家退款申请、撤消、确认、仲裁申请、撤消、确认152.6商户单笔订单查询172.8通知消息及查询返回182.8其他22第 3 章商户开发22 第 1 章 业务说明买家在商户网站进行C2C信用购物交易，工行完成买家、卖家、商户手续费的资金转账。信用支付的主要作用是，银行建立中间中转账户，买家支付的资金并不直接转付给卖家，而是先转付到银行的中间账户上，此笔从买家账户到银行中间账户的转账称为预支付；预支付后，商户应通知卖家进行发货处理，买家在接收到货物后确认，如果没有问题则在商户发起确认支付，此时将保留在银行中间账户的资金转付到卖家账户和商户手续费账户。如果买家对于货物存有异议，可以申请部分、全部、当日、隔日的退货处理，当提起申请退货处理后，此时的订单等待卖家进行退货确认，如果卖家允许退货，则在商户发起退货确认，银行将保留在中间账户的资金，部分或者全部的转回买家账户。如果卖家不同意退货，则可以在商户网站拒绝退货，此时订单资金将恢复为保留状态。买家仍可提出申请仲裁，此时银行等待仲裁机构对此笔交易的仲裁确认，如果仲裁机构同意退货，则通知银行，银行将保留在中间账户的资金转回买家账户，如果仲裁机构不同意退货，则恢复订单资金的保留状态。每一笔信用支付的订单设置一个订单有效期。1、在有效期内，买家可以提出申请退货、申请仲裁处理；提出申请后，需卖家确认，系统会累加卖家确认时间到买家申请时间的时差到订单有效期上，保证买家有足够的控制订单的时长。卖家不确认，此笔资金也不能转到卖家账户；2、如果卖家发货后，买家收到货物，没有及时进行支付确认，则在订单超过订单有效期后，商户可以发起超期支付请求，此时银行将在中间账户保留的订单资金转付到卖家账户和商户手续费账户。对于订单有效期，商户有延长的权限，银行提供延长支付到期日接口，商户调用此接口，可以延长原订单提交时设置的到期日，但是不能缩短到期日。对于买家，如果提出了退货申请、仲裁申请，在卖家没有确认前，有权撤销处理，即撤销退货、撤销仲裁。撤销之后，订单资金恢复为保留状态，等待买家确认支付，或者由商户超期支付。业务特色：如果在预支付接口中，商户上送了买家和卖家的手机号码，本订单在最终的确认支付或者超期支付，即资金成功清算后，会自动向买家、卖家发送短信通知。为了方便买家处理，在工行的个人网银提供信用支付指令的查询，并提供针对此订单提出退货申请和仲裁申请的功能，如果买家在工行个人网银提起申请，在申请接受后，银行会主动发送商户通知，让商户记录的订单状态与银行同步。为了方便商户处理，在工行的商户服务页面，提供对于信用支付指令的查询，以及对于申请退款的订单，提供向买家退款功能；对于超期订单，提供向卖家支付功能；当商户员工在工行商户服务页面完成资金处理后，银行会主动发送商户通知，让商户记录的订单状态与银行同步。由于采用HTTP协议进行商户的通知，HTTP连接的不可靠性造成会有掉单的情况，提供C2C信用支付查询接口，商户可以调用此接口来同步商户和银行之间的订单状态。允许买家申请部分退货，部分退货可以发起多次，但是退货总额不能超过订单总金额。商户可以在商户服务页面查询一笔订单对应的多笔退货记录。资金流向图：银行端订单状态图：注： 等待银行资金监管、等待银行清算、退款处理中、仲裁处理中，4个状态为银行处理时的中间状态，在这些状态时，不接收商户或买家发起新的申请。 对于处于交易失败、清算失败的订单，商户仍可重新提交，最终实现订单的提交和资金清算，如果多次尝试不成功，需检查自身程序和系统运行情况，或者与工行联系。 “资金银行监管中”即上文描述的订单资金保留状态。 所有银行端的状态变化，会根据此图判断现有状态，是否允许处理，然后到下一个状态。C2C信用支付交易中，银行提供了多个商户接口，具体内容见下章。这些接口中只有两个需要买家参与，并且有银行和客户的交互页面，即买家预支付、买家提前支付；这两个交易都是商户形成接口提交数据，然后返回买家的浏览器，这些数据通过买家浏览器POST到银行接收入口，并建立买家到银行的SSL连接，完整买家的交易授权，如买家使用静态支付密码、动态口令卡、U盾证书签名。其他的接口都是商户直接访问银行网站，没有客户的参与，没有银行页面。由于此交易状态多，而且能够从商户、银行分别发起交易，从而使订单状态变化，建议商户开发时，判断自身状态，根据规则判断能否修改成下一个状态，此判断在一个事务中完成。并且对于银行的通知消息，做好短时接收到多笔通知、或者掉单的程序处理。银行的通知消息会返回银行的时间，商户应根据通知消息中的时间判断银行端此订单的最终状态。对于最晚通知之前的部分通知可以忽略，只要最终状态和银行一致即可。商户提交的内容需要按照具体接口说明组织明文数据，注意格式和大小写；并根据要求使用工行安全API和商户API证书进行商户签名。对于银行返回的通知信息，需要按照接口定义，组织明文，并使用安全API和银行公钥，对银行通知进行验签，保证银行通知的准确，同时建议比较返回的通知的交易数据，与商户数据进行比较，如发现不一致及时分析并与银行联系。第 2 章 商户接口个人网银提供C2C信用支付统一的入口地址“https:/银行地址/servlet/ICBCINBSEBusinessServlet”，系统会根据接口名称和版本进行判断，然后进行处理；注意提交的action地址，预支付、提前支付是通过客户提交，提交的地址是“/servlet/ICBCINBSCreditCustServlet”，剩下的接口是商户服务器直接提交的，地址是“/servlet/ICBCINBSCreditMerServlet”。 买家预支付和提前支付需要和客户进行交互确认，其提交方式是商户订单通过客户浏览器提交银行，建立单向ssl；提交form表单；但是所有交易数据统一为xml格式，将整个xml报作为一个数据项提交，xml使用BASE64编码。 除买家预支付和提前支付的其他接口都是商户服务器和银行服务器直接建立单向ssl连接，post方式提交，交易数据使用xml； 商户通知：1、商户服务器和银行服务器直接建立单向ssl连接的交易，银行处理后，在原连接中返回商户通知；2、对于客户post到银行，以及客户直接在银行的操作，商户在商户服务页面的操作，需要银行主动发送变更通知给商户，此时使用http连接方式，post方式提交，交易数据使用xml； 银行的主动通知和商户直接和银行交互后的返回，采用统一的数据格式返回，即下面的“通知消息及查询返回接口”。即通常情况下各接口的请求，银行都是返回相同的通知格式，其中的各字段如果有值则返回，如果没有值则为空或初始值； 传输数据的编码方式是GBK，XML格式串需要XML头，即 对于需要和客户交易的两个交易，定制错误页面，在其上增加返回商户的链接，当点击时，网银后台发送通知，同时返回客户端，通过客户端再重定向到商户，其中含通知消息。如果准备通知消息数据时程序异常，后台将不发送通知，前台也返回商户时也不含通知消息。 接口版本号是全部接口的统一的版本号，不是某一个接口自己的属性；使用接口提交的处理，返回就使用的通知消息格式。 商户订单的标识：商户号、订单号、商户提交日期（注意：没有商户提交时间）要求商户在其自身系统一天内的订单号不能重复。对于预支付失败的指令，允许重新提交，此时订单标识不能变，即商户号、订单号、商户提交日期三项不变，但是商户提交时间可以变，而且总的提交时间在银行前后三小时范围内。所有接口都是使用form表单的方式进行提交，表单包含3个数据项【interfaceName信用支付接口名称】、【interfaceVersion信用支付接口版本】、【CREDIT_PAY_DATA信用支付交易数据】；样例：注：CREDIT_PAY_DATA的值需base64编码。Action地址根据不同接口不同。2.1 买家预支付Xml格式字段说明：变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=23必输，取值：“ICBC_PERBANK_CREDIT_PAY”接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期时间来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。其他商户接口中都需要上送此时间检验联名标志verifyJoinFlag=1必输， 取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；取值“0”：不检验客户是否与商户联名，按上送金额扣帐。卖家卡号/账号sellerAcctMAX(19)必输， 支持账户和卡号卖家姓名sellerNameMAX(60)必输， 注意是60字节商户手续费入账账号merAcctNumMAX(19)必输， 手续费入账账户户名merAcctNameMAX(19)必输， 订单金额amountMAX(10)必输， 客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。币种currTypeMAX(3)默认人民币“001”有效期长度orderPeriodMAX(4)由于商户和银行存在时间差，要求商户提交有效期长度，银行根据自己时间计算到期日单位小时最小值：24小时最大值：360小时，即15天已含运费金额carriageAmtMAX(18)选输以分为单位商品名称goodsNameMAX(60)选输单位字节商品编号goodsNoMAX(30)选输单位字节商品数量goodsNumMAX(10)选输单位字节商户提示merHintMAX(120)选输单位字节买家手机号码buyerPhoneNum11选输支持移动、联通手机接收交易成功通知卖家手机号码sellerPhoneNum11选输支持移动、联通手机接收交易成功通知接收支付结果信息通知程序地址merURLMAX (200)必输， 使用HS通知类型的商户用来接收工行订单支付结果的URL；银行使用HTTP协议POST方式向此地址发送通知信息；目前只支持80端口。使用“AG”通知类型的商户,该字段可以为空或者不上送该字段；但在签名数据中必须包含此项，取值可为空。取值举例：/getICBCPayResult.jsp（注意需要写上“http:/”）返回商户地址backMerURL必输，交易结束返回商户URL，完成闭环返回商户数据backMerData必输，交易结束返回商户URL时，post的保留数据（可用做维护原有商户端session）订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行 然后进行BASE64编码后得到的字符串。（格式单独说明）商户证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。商户接收银行通知地址为必输项，且银行保存，用于后续的银行端变更指令状态（如银行端申请仲裁、撤销仲裁、退货确认、超期付款交易）时进行通知；也用于买家预支付和提前支付；返回商户地址为必输项，买家预支付和提前支付除后台发送通知外，在结果页面，将客户重定向到商户时，仍然向商户提交结果信息。对于有页面交互的（类似于B2C的）交易，主要使用通过客户端浏览器重定向到商户的方式，返回交易结果信息，将后台通知作为辅助手段，以后可能取消后台的发送。Xml格式说明：（即将此xml进行base64编码作为CREDIT_PAY_DATA的值）格式一定，允许空值；注意整个字符串中不要有空格、tab、回车换行等控制字符，要作为字符串提交。（下面的接口也都是这样）订单签名数据merSignMsg的格式：按照如下格式，组织签名的明文数据，都是key=value的形式，然后使用&符号连接；没有取值的变量就留空，但不能是null；（下面的接口也都是这样）interfaceName=&interfaceVersion=&orderID=&amount=&currType=&merOrderTime=&orderPeriod=&sellerAcct=&sellerName=&merID=&merAcctNum=&merAcctName=&verifyJoinFlag=&buyerPhoneNum=&sellerPhoneNum=&merURL=&backMerURL=&backMerData=2.1 买家提前支付使用form方式提交，提交数据名称是CREDIT_PAY_DATA=XXXXXXXX表示BASE64编码的xml格式的字符串变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=29必输， 取值：“ICBC_PERBANK_CREDIT_AHEAD_PAY”接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss原提交订单时上送的时间交易日期时间merTranTime=14必输， 格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。商户提示merHintMAX(120)选输商户收费金额feeAmtMAX(10)必输， 可为零，以分为单位，必需符合金额标准。返回商户地址backMerURL必输，交易结束返回商户URL，完成闭环返回商户数据backMerData必输，交易结束返回商户URL时，post的保留数据（可用做维护原有商户端session）订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行 然后进行BASE64编码后得到的字符串。（格式单独说明）商户证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。订单签名数据merSignMsg的格式：interfaceName=&interfaceVersion=&orderID=&merOrderTime=&merTranTime=&feeAmt=&merID=&backMerURL=&backMerData=2.1 超期商户支付变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=31必输， 取值：ICBC_PERBANK_CREDIT_OVERDUE_PAY接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss原提交订单时上送的时间交易日期时间merTranTime=14必输， 格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。商户收费金额feeAmtMAX(10)必输， 可为零，以分为单位，必需符合金额标准。订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行 然后进行BASE64编码后得到的字符串。（格式单独说明）商户证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。订单签名数据merSignMsg的格式：interfaceName=&interfaceVersion=&orderID=&feeAmt=&merOrderTime=&merTranTime=&merID=2.4 商户延期支付到期日变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=31必输， 取值：ICBC_PERBANK_CREDIT_DEFER_PAY接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss原提交订单时上送的时间交易日期时间merTranTime=14必输， 格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。要延长的有效期长度deferOrderPeriodMAX(4)必输， 在当前系统时间的基础上累计延长有效期为新的订单到期时间，要求系统时间+要延长的有效期时间订单当前到期时间单位小时，整形延期描述deferMsgMAX(200)选输注意最大200字节订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行 然后进行BASE64编码后得到的字符串。（格式单独说明）商户证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。订单签名数据merSignMsg的格式：interfaceName=&interfaceVersion=&orderID=&merOrderTime=&merTranTime=&merID=&deferOrderPeriod=&deferMsg=2.5 买家退款申请、撤消、确认、仲裁申请、撤消、确认变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=31必输， 取值：ICBC_PERBANK_CREDIT_MODIFY接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss原提交订单时上送的时间交易日期时间merTranTime=14必输， 格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。处理动作refundAction=1必输， 0申请退款1撤消退款2同意退款3拒绝退款4仲裁申请5撤消仲裁6同意退款仲裁7拒绝退款仲裁处理金额refundAmtMAX(10)必输， 单位：分处理描述refundActionMsgMAX(200)注意最大200字节订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行 然后进行BASE64编码后得到的字符串。（格式单独说明）商户证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。撤消退款和撤消仲裁时不检查对于买家不受订单到期日得限制，即买家可以在超期之后进行撤消动作，撤消不影响到期日。订单签名数据merSignMsg的格式：interfaceName=&interfaceVersion=&orderID=&merOrderTime=&merTranTime=&merID=&refundAction=&refundAmt=&refundActionMsg=注：此接口为了便于区分请求的处理，将处理动作单独作为一个表单输入项，商户提交的表单内容如下：2.6 商户单笔订单查询变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=23必输， 取值：“ICBC_PERBANK_CREDIT_ORDER_QUERY”接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期时间来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss提交订单时商户端时间交易日期时间merTranTime=14必输， 格式为：YYYYMMDDHHmmss要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。订单签名数据merSignMsg无限制必输，商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行 然后进行BASE64编码后得到的字符串。（格式单独说明）商户证书公钥merCert无限制必输，商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。订单签名数据merSignMsg的格式：interfaceName=&interfaceVersion=&orderID=&merOrderTime=&merTranTime=&merID=2.8 通知消息及查询返回变量名称变量命名长度定义（以字节为单位）说明接口名称interfaceName=23必输， 取值：“ICBC_PERBANK_CREDIT_STATE”接口版本号interfaceVersion=7必输， 取值：“”订单号orderIDMAX(30)必输， 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期时间来唯一确认一笔订单的重复性。商户代码merIDMAX(20)必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。订单日期时间merOrderTime=14必输， 格式为：YYYYMMDDHHmmss提交订单时商户端时间卖家卡号/账号sellerAcctMAX(19)隐藏个人账户和卡号中间4位倒数58位如：95588002001*2413卖家姓名sellerNameMAX(60)隐藏名字如：张*商户手续费入账账号merAcctNumMAX(19)隐藏中间4位倒数58位手续费入账账户户名merAcctNameMAX(19)订单金额amountMAX(10)客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。商户收费金额feeAmtMAX(10)必输， 可为零，以分为单位，必需符合金额标准。币种currTypeMAX(3)默认人民币“001”有效期orderExpireMAX(14)YYYYDDMMhhmmss订单状态orderStateMAX(2)0资金银行监管中1交易失败2等待银行资金监管3清算成功4清算失败5等待银行清算6已全额退款7申请退款8退款处理中9申请仲裁10仲裁处理中是否退款标志refundFlagMAX(1)0-未退款1-退款存在一笔成功退款此值就一直为“1”累计退款金额refundAmtSumMAX(10)申请退款/仲裁金额appRefundAmtMAX(10)买家手机号码buyerPhoneNum11支持移动、联通手机接收交易成功通知卖家手机号码sellerPhoneNum11支持移动、联通手机接收交易成功通知接收支付结果信息通知程序地址merURLMAX (200)必输， 使用HS通知类型的商户用来接收工行订单支付结果的URL；银行使用HTTP协议POST方式向此地址发送通知信息；目前只支持80端口。使用“AG”通知类型的商户,该字段可以为空或者不上送该字段；但在签名数据中必须包含此项，取值可为空。取值举例：/getICBCPayResult.jsp（注意需要写上“http:/”）银行通知时间bankNotifyTimeMAX(14)YYYYMMDDhhmmss银行签名数据bankSignMsg无限制（格式单独说明）请求类型requestTypeMAX(2)0买家第一次支付1买家提前支付2超期商户支付3商户延期支付到期日4买家退款申请5买家撤消退款申请6卖家确认退款7买家商户端仲裁申请8买家商户端撤消仲裁申请9买家银行端仲裁申请10买家银行端撤消仲裁申请11商户确认仲裁12商户查询订单13银行端向买家退款14银行端向卖家付款15 银行端支付订单16 银行端拒绝订单请求结果requestResultMAX(1)0成功1失败2等待处理