('某银行快捷支付接口规范(DOCX38页)上海银行-快捷支付接口规范(版本号v3.6.6)前言本文档介绍上海银行“快捷支付”的技术标准此接口标准适应借记卡快捷支付及信用卡快捷支付。其中包括业务处理与系统交互方式、报文的语法与语义、网络连接方式、安全规范等。第1章文档概述1.1介绍1.1.1概述本文档阐述的技术标准，为更加快捷安全的互联网支付结算提供了解决方案。1.1.2目标读者本文档的主要目标读者是银行与商户的技术实施人员，也可供业务人员参考。1.1.3最近修订版本号作者内容提要核准人发布日期1.0黄敦迪定义上海银行快捷支付接口规范蔡红林2012-06-12.0黄敦迪删除快捷支付业务概述；调整错误代码；重定义身份鉴权报文头；删除单笔提现接口；删除批量交易明细查询，新增单笔交易明细查询黄敦迪2012-6-133.0黄敦迪增加批量交易明细查询，修改错误代码黄敦迪2013-3-113.1黄敦迪修改身份鉴权、网上支付、单笔退款、批量退款接口，加入了卡代号等2013-3-123.2黄敦迪鉴权需中账户姓名改为必输2013-4-113.3黄敦迪接口实现说明中批量交易查询改为非必须实现的接口。批量交易查询请求报文中加入订单号列表2013-4-193.4彭小波修改身份鉴权接口，CVV2、有效期改为可选字段，增加KoalB64Cert;修改网上支付接口CVV2、有效期改为可选字段，返回报文银行卡改为卡代号，黄敦迪2013-4-223.5.1彭小波批量交易查询增加爱业务规则：订单最多支持10笔;查询的多条订单只返回符合条件的记录。2013-4-283.5.2彭小波为单笔退款增加错误代码：40452013-5-23.5.3黄敦迪单笔交易明细查询应答报文中status枚举值调整及定义errorCode的取值；批量交易查询应答报文TradeInfo清单中的signNo改为cardNo2013-5-113.5.4彭小波错误码不再分类别扩展鉴权的证件类别鉴权中增加校验规则，手机号码必须为11位明确单笔订单查询中的交易日期和时间2013-5-173.5.5彭小波调整错误码描述：2013-5-183006对应描述改为卡号不存在或不支持的银行卡3016对应描述改为银行账户交易失败批量交易查询的交易状态进行调整：0000成功；0001失败3.5.6彭小波3003的errormessage从“身份证号码不匹配”改为“身份证件号码不匹配”2013-5-213.5.7彭小波针对信用卡的CVV2和有效期，增加对应的错误码：3050和30512013-5-243.5.8彭小波身份鉴权增加业务逻辑：CVV2和有效期需同时输入或同时都不输入2013-5-243.5.9彭小波网上支付去除：CVV2和有效期2013-5-273.6黄敦迪删除二级商户信息同步接口，增加单笔撤消接口2013-6-203.6.1彭小波批量交易查询响应报文中交易信息列表tradeInfoList签名要求由”Y”变更为”N”2013-6-263.6.2彭小波新增错误码：4046清算的订单不能做撤销处理2013-6-273.6.3彭小波银行流水号由char(19)统一更改为char(20),修改点：网上支付、单笔退款、单笔撤消2013-6-273.6.4彭小波清算对账中文件格式中银行卡号修正为银行卡代号2013-7-13.6.5彭小波单笔撤消上送报文增加交易金额，同时增加校验：交易金额必须和原订单交易金额一致2013-7-23.6.6彭小波清算对账增加业务规则：信用卡撤消及对应原订单不在清算对账文件内。2013-7-5第2章报文结构上海银行快捷支付报文规范规定了上海银行与商户之间交换报文的处理规范。2.1报文结构快捷支付报文统一采用xml格式。所有的快捷支付报文均以Banksh作为根元素，每个Banksh元素中可以包含多个Message元素。Message元素中包含代表具体的业务的元素，比如CSVReq、CSVRes等。每个业务元素由一系列属性元素构成，不同的业务元素中包含的属性元素有所不同。对于涉及到签约状态修改或者资金变动的业务元素，必须要有与之匹配的Signature元素进行数字签名。作为约定，Banksh元素、Message元素与业务元素均是首字母大写的CamelCase形式，所有的属性元素均是首字母小写的CamelCase形式。以签约请求报文为例，报文的格式如下：… … … … … … … … … … … | … … … … 信息就指订单号;多个订单号之间请用“”分隔；订单最多支持10笔;查询的多条订单只返回符合条件的记录。经过Base64处理的商户证书代码KoalB64Cert/RN商户端读取本地商户证书文件后，再使用上海银行提供的API进行Base64编码后产生的商户证书数据字串。消息扩展extensionON\uf06e“查询”应答报文TQRes(TradeQueryResponse)中文域名对应DTD元素类型出现要求签名要求说明版本号versionchar(7)RN目前版本号：”1.0.1”商户标识instIdchar(15)RY报文发送方的商户标识流水号serialNochar(19)RY该笔查询交易的流水号交易日期和时间datechar(17)RYYYYYMMDDHH:MM:SS交易性质typechar(1)RY0全部;1支付;2退款3;提现交易信息列表tradeInfoListRN交易信息列表，包含多个信息结果代码errorCodechar(4)RY成功SUCC，失败见错误代码错误描述errorMessagechar(256)ON消息扩展extensionONTradeInfo中的每一项中的域如下表所示：交易流水号serialNochar(19)R订单号交易日期时间datechar(17)R支付卡号cardNochar(45)R交易金额amountLong(12)R见金额格式说明手续费chargeLong(12)O预留字段，见金额格式说明(一般都是0)交易货币代码currencychar(3)R交易卡种cardTypeChar(1)R1借记卡2贷记卡3联名卡4其他原流水号originalSerialNochar(19)C退货时对应原支付订单号原交易日期和时间originalDatechar(17)C退货时对应原支付日期交易状态statuschar(4)R0000：成功，0001：失败，0002：银行处理中，0003：银行查无此订单。4.8清算对账4.8.1业务功能当发生网络丢失报文或系统故障时，银行返回给商户的交易应答有可能丢失，造成客户签约银行卡账户中的资金变动与商户账户中的资金变动不一致。除了交易应答丢失产生清算不一致的情况下，还可能因为其它原因（比如系统中的缺陷，或者人为因素）产生清算不一致。清算对账业务的目的是用于商户进行清算对账以避免清算不一致的情况。清算对账文件一般一天产生一次，以银行交易日切为准，上海银行日切时间为晚上21：00；4.8.2业务规则清算对账业务在执行中需要满足以下约束条件：\uf06e银行提供的T日21:00-T+1日21:00发生的快捷支付交易明细；\uf06e银行在T+1日上午8:00点之前主动向商户提供上一清算日的交易明细数据文件。\uf06e当清算对账完成后，并完成差错处理之后，双方直至上一清算日的所有快捷支付交易引起的资金变动必须一致。\uf06e信用卡撤消及对应原订单不在清算对账文件内。4.8.3处理流程清算对账的处理流程如下图所示：1.银行在日切后生成清算对账文件，按照交易时间排序。2.商户按照银行事先约定的下载URL发起下载文件请求。3.银行处理下载请求后，返回文件并在https的response的head域里面的Banksha1域中设置文件摘要，在Banksign域中设置签名。4.商户收到“清算对账”文件后，验签和解密后，从银行提供的清算对账文件中解析出每一条交易记录，与自己在该对账日期的所有快捷支付交易记录进行逐笔核对。找出并生成以下三类交易记录的清单。\uf06eA：银行有，但商户没有的交易记录\uf06eB：商户有，但银行没有的交易记录\uf06eC：双方都有，但内容不一致的交易记录商户对不一致的快捷支付交易记录进行恢复与处理。对于A类交易记录，商户进行交易恢复。对于B类交易记录与C类交易记录，商户人工介入处理，通过核对原始的银行应答指令找出原因并确定该由哪方进行订正。如果存在需要银行进行调整的交易记录，则商户线下提供给银行的需要调整的交易记录清单，以及原始的银行应答指令，由银行在人工核实之后进行处理。4.8.4交互模式4.8.5文件格式\uf06e文件格式文件格式采用以逗号分隔的txt类型文件格式；\uf06e“清算对账”文件结构清算对账文件包括当日银行端发生的所有商户账务交易数据，包括充值、支付、提现、退回（退货）交易，需要特别注意。清算对账文件由汇总项与明细项两部分组成。汇总项为文件第一行，其中包含以下各项：中文名称出现要求备注处理成功总金额R本批处理成功的总金额，格式见金额格式说明处理成功总笔数R本批处理成功的总笔数处理失败总笔数R本批处理失败的总笔数明细项从文件第二行开始直到文件结束，其中每一行包含以下各项：中文名称出现要求备注流水号（订单号）R交易日期时间RYYYYMMDDHH:MM:SS交易类型R1支付;2退款（含借记卡撤消）银行卡代号R手续费O见金额格式说明交易金额R见金额格式说明交易货币代码O原流水号C退货交易时必填原交易日期C退货交易时必填处理状态RY成功；N失败失败原因R如果处理状态为失败，则描述失败的原因。4.8单笔撤消4.4.1业务功能单笔撤消是在发生在成功支付但未清算之前，将该笔交易充值的款项原路退回到快捷支付签约银行卡账户中。撤消必须在商户核实之后，由商户发起。单笔撤消交易为实时交易，即实时从商户结算账户扣取，入个人账户。4.4.2业务规则撤消业务在执行中需要满足以下约束条件：\uf06e撤消业务从商户发起。\uf06e撤消业务必须有对应成功的支付交易。\uf06e撤消的金额需与原支付金额一致。\uf06e撤消的资金只能原路划回原支付的银行卡账户中。\uf06e撤消的订单与原订单相对应，对应的支付与撤消不再在晚间清算4.4.3处理流程4.4.4交互模式在单笔撤消业务中，商户与银行通过请求-应答模式交互。4.4.5报文格式\uf06e“单笔撤消”请求报文SCReq(SinglecancelRequest)中文域名对应DTD元素类型出现要求签名要求说明版本号versionchar(7)RN目前版本号：”1.0.1”商户标识instIdchar(15)RY报文发送方的商户标识订单号orderNumchar(30)RY该笔退款交易的商户订单号,永不重复交易日期和时间datechar(17)RYYYYYMMDDHH:MM:SS卡代号cardCodechar(20)RY鉴权时返回的卡代码交易货币代码currencychar(3)RY见快捷支付货币代码表交易金额amountLong(12)RY交易金额必须和原订单交易金额一致；见金额格式说明原订单号oldorderNumchar(30)RY对应原支付交易的订单号，永不重复原交易日期和时间olddatechar(8)RYYYYYMMDD经过Base64处理的商户证书代码KoalB64Cert/RN商户端读取本地商户证书文件后，再使用上海银行提供的API进行Base64编码后产生的商户证书数据字串。消息扩展extensionON\uf06e“单笔撤消”应答报文SCRes(SinglecancelResponse)中文域名对应DTD元素类型出现要求签名要求说明版本号versionchar(7)RN目前版本号：”1.0.1”商户标识instIdchar(15)RY报文发送方的商户标识订单号orderNumchar(30)RY商户退款订单号,永不重复，同支付时订单号规制交易流水号serialNochar(20)RY银行交易流水号交易日期和时间datechar(17)RYYYYYMMDDHH:MM:SS卡代号cardCochar(RY退款请求中的卡代码de20)结果代码errorCodechar(4)RY成功SUCC，失败见错误代码错误描述errorMessagechar(256)ON消息扩展extensionON第5章网络连接规范有3种网络连接方式:1、公网连接；需商户端通过程序调用方法模拟SSL通讯链路。所有涉及到签约状态变动与资金处理的交易报文与文件，需通过应用层报文数字签名方式以防交易否认。2、VPN连接；链路层通过VPN安全机制保护，使用HTTP协议在双方的服务器之间进行。所有涉及到签约状态变动与资金处理的交易报文与文件，需通过应用层报文数字签名方式以防交易否认。3、专线连接；链路层通过专线安全机制保护，使用HTTP协议在双方的服务器之间进行。所有涉及到签约状态变动与资金处理的交易报文与文件，需通过应用层报文数字签名方式以防交易否认。第6章安全规范本章主要从技术角度阐述快捷支付系统中可能出现的安全威胁，以及通过技术规范来规避安全风险的方式。6.1安全威胁来自网络的安全威胁主要有以下几种：\uf06e信息泄密报文中交换的客户信息与交易指令均有私密性要求。在快捷支付技术规范中，需要确保在网络传输中对客户与交易信息私密性的保护。解决方案：将双方的的通信信道进行加密（见网络连接规范）。\uf06e交易指令篡改如果网络中传输的交易指令被入侵者截获并篡改，就会造成资金处理出现错误，给业务参与方造成损失。因此，在网络传输中，需要保证指令完整性。解决方案：使用数字证书对对报文中的业务数据进行签名（见数字签名）。\uf06e交易指令伪造如果有入侵者冒充商户或者银行发起交易指令就会造成资金在未得到业务参与方的授权下发生流动，给银行、商户或客户带来损失。因此在网络传输与系统处理中，需要保证指令的真实性。解决方案：使用数字证书对对报文中的业务数据进行签名（见数字签名）。\uf06e交易指令否认当发生交易纠纷时，双方需要通过交易指令确定责任方。快捷支付安全规范中需要为交易指令防否认提供技术支持。解决方案：使用数字证书对对报文中的业务数据进行签名（见数字签名），银行与商户均应保留涉及资金变动的交易报文日志（见报文日志管理）。\uf06e交易指令重播入侵者也可能尝试通过截获网络中传输的交易指令，并多次重播的方式试图发起未经授权的快捷支付交易。在技术规范中，需要防止交易指令重播引起的未授权交易。解决方案：凡涉及到资金变动的交易指令，流水号必须唯一。银行与商户均需要保证同一流水号的交易指令只能执行一次。6.2数字签名6.2.1数字签名和验签要求每个交易的签名原文是按照报文接口定义是否需要进行签名按照顺序进行组合，分隔符是“”，然后通过签名的API取得签名密文，放在请求或者返回报文域的Signature标签里面。比如“银行发起撤销交易”，银行发起的请求交易接口定义需要对“商户标识”，“交易日期和时间”，“协议号”字段进行签名，比如对010101商户的ABCDEF协议号进行撤销，则签名原文是“0101012009101109:08:02ABCDEF”，假设经过签名之后的密文是XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX，那么需要把这个签名密文放置到Signature标签里面。商户收到银行的撤销交易请求之后，需要对银行的签名进行验签，那需要按照API的要求，从请求的报文里面取得签名的原文和密文，进行验签。原文按照接口定义的“商户标识”，“交易日期和时间”，“协议号”的标签中取值，进行竖线链接，然后从Signature标签确定密文，进行验签。强调：本地用GBK编码签名，并统一以UTF-8编码提交。银行提供JAR包，并公布调用方式；签名例子://待签数据,原文StringszData=sourceMsg;//构造签名实例SvsSignsigner=newSvsSign();//初始化签名证书和私钥，即.pfx(或.p12)文件名和口令（口令不能为空,口令为商户操作员下载商户证书后从浏览器中导出pfx文件格式时设置的私钥保护口令）signer.initSignCertAndKey("E:\\\\KoalSvsSoft\\\\cert\\\\test1.pfx","私钥保护口令如123456");//签名，获得签名结果（Base64编码）StringszRet=signer.signData(szData.getBytes(“GBK”));验签例子：//验证数据签名StringszData=signDataStr;szSignedData=signData;intnRet=SvsVerify.verify(szData.getBytes(),szSignedData,"E:\\\\bankofshanghai_test.cer");if(0==nRet){System.out.println("[OK]VerifyReturnOK");}else{System.out.println("[ERROR]VerifyReturnERROR:"+nRet);}6.3报文日志管理为了做到交易指令防否认，银行与商户均应保留涉及资金变动的交易报文日志，日志中包括完整的报文、报文签名、接收时间以及源IP地址。交易报文日志应该妥善管理，避免泄密或者被破坏。第7章附录7.1金额格式用货币单位的最小单位表示的金额，其中不包含任何标点，最多12位。例如：如果交易金额为123.45RMB，则该项内容为12345。（但是在页面上显示：人民币是以元为单位，交易中的金额都是以分为单位）7.2货币代码表根据GB/T12406-1996，货币代码字段使用的3位定长数字如下表所示。国家、地区名称货币名称货币代码中国人民币元156中国香港港元344中国澳门澳门元446美国美元840英国英镑826法国法国法郎250德国马克278俄罗斯卢布810日本日元392加拿大加元124瑞士瑞士法郎756瑞典瑞典克朗752意大利意大利里拉380西班牙西班牙比塞塔724葡萄牙葡萄牙埃斯库多620荷兰荷兰盾528比利时比利时法郎056芬兰马克246挪威挪威克朗578希腊德拉克马300奥地利先令040丹麦丹麦克朗208澳大利亚澳大利亚元036新西兰新西兰元554巴西克鲁赛罗076南非兰特710埃及埃及镑818伊拉克伊拉克第纳尔368伊朗伊朗里亚尔364沙特阿拉伯沙特里亚尔682科威特科威特第纳尔414阿联酋UAE迪拉姆784泰国铢764新加坡新加坡元702印尼卢比360马来西亚马来西亚458林吉特菲律宾菲律宾比索608南朝鲜圆410印度印度卢比356',)
下载
下载
下载
下载
下载
下载
下载
下载
下载
下载
下载
下载