闪信互联商户对接文档V1.4

1/24闪信互联商户接口技术集成文档V1.32/24修订记录修订日期修订人动作修订说明版本号2014-11-06刘芳创建1.02015-04-27刘芳修改增加非自营商户信息字段1.12015-05-11刘芳修改增加商户H5下单接口1.22015-09-09于江波修改合并商户下单接口，增加商户下单接口字段1.32015-12-30熊冬修改新版H5收银台提交URL1.43/24目录1引言............................................................................................................................................41.1文档概述.............................................................................................................................41.2业务术语.............................................................................................................................41.3通讯模式.............................................................................................................................41.3.1后台通讯模式..............................................................................................................................................41.3.2如何验证是否闪信互联请求:.....................................................................................................................51.4安全规范.............................................................................................................................51.4.1数字签名.....................................................................................................................................................51.4.2提交URL....................................................................................................................................................62商户接口....................................................................................................................................72.1商户下单接口.....................................................................................................................72.2商户订单查询接口...........................................................................................................122.3商户退款接口...................................................................................................................162.4商户后台结果通知接口...................................................................................................203附录..........................................................................................................................................233.1错误码信息.......................................................................................................................234/241引言1.1文档概述阅读对象：合作商户技术开发人员。。1.2业务术语返回页面跳转同步通知。闪信互联根据得到的数据处理完成后，当前页面从商户的页面自动跳转到闪信互联的收银台页面。请求通过HTTPS协议把需要传输的数据发送给接收方的过程。通知服务器异步通知。闪信互联根据得到的数据处理完成后，闪信互联的服务器主动发起通知给商户的网站，同时携带处理完成的结果信息反馈给商户网站。请求参数请求参数是商户在与闪信互联进行数据交互时,提供给闪信互联的请求数据,以便闪信互联根据这些数据进一步处理。1.3通讯模式商户接口全部采用https协议通讯，保证通讯链路数据传输的安全，同时全部采用数字签名保证交易数据不被篡改。将整个串做一次加密保证数据不被窃取。1.3.1后台通讯模式后台通讯模式指商户后台服务器与闪信互联系统后台服务器直接通讯的模式，主要用于5/24非页面交互的交易，比如：商户订单查询。商户根据接口要求组织报文后直接向闪信互联系统服务器发起交易请求，闪信互联系统处理完成后返回结果报文。1.3.2如何验证是否闪信互联请求:当商户获取到待签名字符串后，需要把私钥直接拼接到待签名字符串后面，形成新的字符串，利用MD5的签名函数对这个新的字符串进行签名运算，从而得到32位签名结果字符串。此时这个新的字符串需要与请求参数中的hmac的值进行验证是否相等，来判断签名是否验证通过。1.4安全规范1.4.1数字签名为保证数据传输过程中的数据真实性，完整性和不可抵赖，我们需要对数据进行数字签名，在接收签名数据之后迚行签名校验。签名算法为MD5。MD5签名算法：MD5本是一种摘要生成算法，通过在待签名数据之后特殊处理加上一串私密内容(指令发送、接收双发事先规定好的，我们称其为商户密钥)，用于进行签名。签名机制如下：1.接口的公钥证书和签名字段不参与组成签名原文串。2.待签名原文是请求参数按照商户接口中请求参数自上而下的顺序组装成的字符串。没有值的为空字符串。例如提交的参数为：param1=value1¶m2=value2&…¶mN=valueN，则待签名原文为：value1value2…valueN3.当拿到请求时的待签名字符串后，需要把私钥直接拼接到待签名字符串后面6/24，形成新的字符串，例如私钥为123，则上一步待签名字符串加上私钥后组成的新字符串为value1value2…valueN123利用MD5的签名函数对这个新的字符串进行签名运算（DigestUtils.md5Hex()），从而得到32位签名结果字符串(该字符串赋值于接口请求参数中的hmac)。1.4.2提交URL采用POST方式提交请求7/242商户接口通讯协议为https,使用POST提交请求参数。接口结构：一般由两部分组成，接入部分与通知返回部分。接入部分即为传递参数等信息组合成超级链接，并用该链接来进行跳转。通知返回部分则是闪信互联服务器对该笔订单处理完成后，通知与返回该笔订单的详细信息到商户服务器，商户服务器接收到后，并对其进行数据数据。2.1商户下单接口当用户在商户提供的网站中提交消费订单时，商户根据报文格式组好数据包后调用闪信互联下单接口，完成本次订单在闪信互联支付系统的创建过程，调用接口前需要对请求参数做非空以及合法性校验，确保信息无误后在进行下单,闪信互联系统返回下单结果并跳转至闪信互联收银台页面，此接口支持PC及H5页面的跳转（注意请求地址及参数区别）。下单时会按照商户的费率收取一定的手续费。闪白条合作商户2：发起请求数据4：返回响应数据3：请求数据处理5：对响应数据进行处理1：构造请求数据(1)构造请求数据8/24商户根据闪信互联提供的接口规则，通过程序生成得到签名结果及要传输给闪信互联的数据集合。构造请求参数时，需要对必填参数的非空性和合法性进行校验，其中“订单金额”以“元”为单位，“字符集”、“接口类型”、“版本号”、“签名方式”按后面的请求参数说明中的值写死就可以。有效时间可以以“分钟”或者“小时”或者“天”为单位，但最大值不能超过15天。“备用字段“为预留字段，不需要填写，“商户订单号”不能重复，一个商户订单号代表一个订单，如果商户订单号重复，则返回原订单，如果原订单的支付状态非“初始化”状态，则下单失败。如果订单需要分账处理，在后面会有较详细的说明。签名字段的生成请阅读1.4.1数字签名部分。采用form表单提交数据。(2)发送请求数据把构造完成的数据集合，通过页面链接跳转或表单提交的方式传递给闪信互联。(3)闪信互联对请求数据进行处理闪信互联收到请求后，会先进行安全校验等验证，一系列验证通过后便会处理这次发送过来的数据请求。(4)返回处理的结果数据用户下单后，闪信互联会在程序上自动重新构造URL地质链接，在用户当前页面上通过自动跳转的方式跳到闪信互联的收银台页面，在闪信互联收银台支付完成后，则会通过商户在请求时设定好的后台通知地址（参数notifyUrl）进行后台通知。通过点击链接跳转回商户在请求时设定好的页面通知地址（参数pageUrl）,并把数据（商户下单时的订单号(mercOrderNo)和支付结果(paySts成功值为:S)）反馈给商户网站。支付结果以后台通知为准，pageUrl主要是做页面跳转,将页面重新返回到商户网站。(5)商户对获取的返回结果数据进行处理商户在同步通知处理页面(参数pageUrl指定页面文件)获取闪信互联返回的结果数据9/24后，可以结合自身网站的业务逻辑进行数据处理。分账参数详细说明:分账参数的格式为:分账商户1^分账金额1^备注|分账商户2^分账金额2^备注|分账商户3^分账金额3^备注|。。。备注字段可以为空。分账商户不能为下单商户，分账商户不能重复，分账金额不能大于订单金额，分账金额总和不能大于订单金额。订单的手续费从下单商户出，分商户的手续费会给下单商户。例如一笔订单100块钱，主商户A分账给了分账商户B，40块钱，假如收取A，2块钱，则这2块钱会给闪信互联，假如收取B，1块钱，则这1块钱会给A。最后的金额为A得了60-2+1=59，B得了40-1=39。PC版请求地址：测试请求URL：生产请求URL：http