小二支付网银接口对接技术文档V1.0版..doc

小二支付网银接口说明文档小二支付平台网银接口对接技术文档商户接入指南 2014年12月30日目录第一章 文档描述31、文档说明32、阅读对象3第二章 系统原理31、术语定义32、消费流程33、查询流程44、系统加密4第三章 网银接口定义41、上行过程接口定义（商户系统发起请求）42、下行异步通知过程接口定义（小二支付接口发起请求）7第四章 查询流程接口定义10附录1：小二支付网银接口银行类型说明11第一章 文档描述1、文档说明本说明文档用于指导小二支付商户实现与小二支付网银接口的顺利对接。请相关技术人员详细阅读本文档。2、阅读对象商户开发人员。第二章 系统原理1、术语定义商户：指已独立拥有在线销售系统，并成为小二支付网银接口系统会员，且已使用或者将使用小二支付网银接口实现收付费或其他相关功能需求的企业或者个人。外部接入接口：指小二支付通过统一的方式接受外部请求的接口。商户系统：指使用小二支付外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。用户：指在商户系统内进行消费的企业或者个人。商户ID： 指小二支付为使用外部接入接口的商户统一分配的唯一标识。商户密钥：指商户在和小二支付确定合作意向时小二支付为商户提供的32位字符串。该信息作为商户系统和小二支付交互时身份确认的依据，需商户妥善保管。2、消费流程通常，一次支付最少包括2个交互过程。第一个过程是商户系统将在线支付等信息提交到小二支付接口的过程，称之为上行过程。第二个过程是在支付完成后，小二支付接口通过server to server方式将支付结果告知商户系统的过程，称之为下行异步通知过程。3、查询流程在商户系统将订单成功提交给小二支付接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。4、系统加密小二支付接口采用MD5加密方式对传输数据进行签名验证，具体请参考相关接口定义。对MD5加密后的签名值，请注意结果全部为小写。为了确保签名值不是因为MD5加密算法而导致结果不正确，请各商户在调用接口前对字符串12345678使用MD5加密算法进行加密，若加密结果为25d55ad283aa400af464c76d713c07ad则表示MD5加密正常。第三章 网银接口定义1、上行过程接口定义（商户系统发起请求）1、 接入URL：/bankPay/bank.html2、接入方式：GET/POST方式3、请求协议参数：表1 上行过程请求协议参数说明参数名参数可空加入签名说明商户IDuseridNY商户id银行类型bankidNY银行类型，具体请参考附录1金额moneyNN单位元（人民币），2位小数，最小支付金额为0.02商户订单号orderidNY商户系统订单号，该订单号将作为小二支付接口的返回数据。该值需在商户系统内唯一，小二支付系统暂时不检查该值是否唯一下行异步通知地址urlNN下行异步通知过程的返回地址，需要以http:/开头且没有任何参数支付用户IPipNN用户在下单时的真实IP，小二支付接口将会判断玩家支付时的ip和该值是否相同。若不相同，小二支付接口将提示用户支付风险备注消息extYN备注信息，下行中会原样返回。若该值包含中文，请注意编码!默认utf-8MD5签名signN-32位小写MD5签名值代理商idagentidNN代理商id,没有则留空,请勿传null4、MD5签名说明待签名数据为表1中加入签名列值为Y的参数以及商户密钥。具体MD5签名源串及格式如下：userid=0&orderid=1&bankid=2&keyvalue=3其中，keyvalue 为商户密钥, 在小二支付商户后台获取。5、特别说明：根据HTTP协议要求，提交参数的值中若存在特殊字符（如：空格、等）时，为使小二支付接口能接收到正确的参数，这些特殊字符需要做URL Encoding。需特别注意的是，此时待签名数据应该是原生值而不是encoding之后的值。2、下行异步通知过程接口定义（小二支付接口发起请求）1、接入URL：过程1中请求参数callbackurl值 2、接入方式：GET方式3、请求协议参数：表2 下行过程请求协议参数说明参数名参数加入签名说明商户订单号orderidY上行过程中商户系统传入的orderid。订单结果succYY:支付成功；N：支付失败(为大写)订单金额ovalueY订单实际支付金额，单位元小二支付订单号hetuordernoN小二支付接口系统内的订单Id商户IDuseridN商户id备注信息extN备注信息，上行中原样返回订单结果说明msgN订单结果说明MD5签名sign-32位小写MD5签名值4、MD5签名说明：待签名数据为表2中加入签名列值为Y的参数以及商户密钥，签名顺序为表2中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：orderid=&hetuorderno=&userid=&oValue=&succ=&keyvalue=其中，keyvalue为商户密钥, 在小二支付商户后台获取。5、特别说明： 下行异步通知过程在整个支付流程中只有在支付成功才会存在。商户系统在收到下行通知过程后，首先通过sign验证各个参数正确性,再向小二支付接口返回结果。sign验证正确,则向页面写入 “ok” ; 否则写入”error”;并立即调用小二支付的订单查询接口(第4章).6、注意事项： 在收到小二支付接口订单下行异步通知结果时，商户系统需首先验证订单通知的合法性，如果不合法，则不要更新商户系统上的订单状态。 商户系统内订单状态和订单实际金额务必以此次小二支付接口订单异步通知的结果为准。 商户系统在成功提交订单后，在未没有收到小二支付接口异步通知结果时，请不要更新商户系统上的订单状态。 商户系统收到异步通知结果后，处理流程可表示为：if(返回参数同表2表述不同) 同步返回小二支付接口 “error”if(签名正确) if（succ = “Y”） 按照成功处理商户系统内订单，订单实际金额为ovalue else 按照失败处理商户系统内订单 同步返回小二支付接口 ”ok”else 同步返回小二支付接口 ”error”总之 收到下行请求时，一定要要返回。不管是什么内容。若下行请求url 失败，系统会重试2次，若还是请求不到，则会停止下行请求。商户则可以在小二支付商务后台手动补单或调用查询接口查询订单状态.第四章 查询接口定义1、接入URL：/bankPay/query.html2、接入方式：GET方式3、请求协议参数：表4 查询流程请求协议参数参数名参数加入签名说明商户订单号orderidY需查询的商户系统订单号商户IDuseridY商户id，由小二支付分配。MD5签名sign-32位小写MD5签名值sign 为组合验证串，采用md5加密，MD5组合源串如下userid =& orderid=&keyvalue=其中，keyvalue为商户密钥, 在小二支付商户后台获取。4、返回协议参数(JSON格式)表5 查询流程返回协议参数参数名称参数含义长度备注returncode售卡结果MAX(20)“-1”代表无支付记录“0”代表支付失败，“1”代表支付成功，message错误信息Max (100)returncode= 0时才有值realmoney支付金额Max(10)订单实际支付金额usermoney结算金额Max(10)结算给用户的金额(实际金额乘以用户比例)附录1：小二支付网银接口银行类型说明表7 小二支付接口银行类型说明编号类型ABC中国农业银行BOC中国银行CCB中国建设银行CNCB中信银行ICBC中国工商银行CMB招商银行CIB兴业银行PSBC邮政储蓄SHB上海银行SRCB上海农村商业银行