接口文档说明示例

支付网关说明文档by:Q294500001目录##联盟支付网关说明文档........................................................................错误!未定义书签。目录..................................................................................................................................................1第一章文档描述..............................................................................................错误!未定义书签。1、文档说明.............................................................................................................................12、阅读对象.............................................................................................................................1第二章系统原理.............................................................................................................................21、术语定义.............................................................................................................................22、消费流程.............................................................................................................................23、查询流程.............................................................................................................................24、系统加密.............................................................................................................................2第三章网银接口定义.....................................................................................................................31、同步过程接口定义（商户系统发起请求）.....................................................................32、下行异步通知过程接口定义（##联盟接口发起请求）.................................................53、下行同步通知过程接口定义（##联盟接口发起请求）.................................................7第四章查询流程接口定义.............................................................................................................8第五章订单外部查询独立网址......................................................................错误!未定义书签。附录1：##联盟支付网关银行类型说明........................................................................................9第一章文档描述1、文档说明本说明文档用于指导##联盟商户实现与##联盟网银接口的顺利对接。请相关技术人员详细阅读本文档。2、阅读对象商户开发人员。第二章系统原理1、术语定义商户：指已独立拥有在线销售系统，并成为##联盟网银接口系统会员，且已使用或者将使用##联盟网银接口实现收付费或其他相关功能需求的企业或者个人。外部接入接口：指##联盟通过统一的方式接受外部请求的接口。商户系统：指使用##联盟外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。用户：指在商户系统内进行消费的企业或者个人。商户ID：指##联盟为使用外部接入接口的商户统一分配的唯一标识。商户密钥：指商户在和##联盟确定合作意向时##联盟为商户提供的16位字符串。该信息作为商户系统和##联盟交互时身份确认的依据，需商户妥善保管。2、消费流程通常，一次支付最少包括2个交互过程。第一个过程是商户系统将在线支付等信息提交到##联盟接口的过程，称之为上行过程。第二个过程是在支付完成后，##联盟接口通过servertoserver方式将支付结果告知商户系统的过程，称之为下行异步通知过程。如果用户在跳转到##联盟接口完成支付操作后，需要##联盟接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括第三个流程，下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。3、查询流程在商户系统将订单成功提交给##联盟接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。4、系统加密##联盟接口采用MD5加密方式对传输数据进行签名验证，具体请参考相关接口定义。对MD5加密后的签名值，请注意结果的大小写务必正确。为了确保签名值不是因为MD5加密算法而导致结果不正确，请各商户在调用接口前对字符串1234567890abcdefghijklmnoprstuvwxyz使用MD5加密算法进行加密，若加密结果为##################################则表示MD5加密正常。第三章网银接口定义1、同步过程接口定义（商户系统发起请求）1、接入URL：http://************/chargebank.aspx(最新地址)2、接入方式：GET方式3、请求协议参数：表1同步过程请求协议参数说明参数名参数可空加入签名说明商户IDparterNY商户id，由##联盟分配银行类型typeNY银行类型，具体请参考附录1金额valueNY单位元（人民币），2位小数，最小支付金额为0.02商户订单号orderidNY商户系统订单号，该订单号将作为##联盟接口的返回数据。该值需在商户系统内唯一，##联盟系统暂时不检查该值是否唯一下行异步通知地址callbackurlNY下行异步通知过程的返回地址，需要以http://开头且没有任何参数下行同步通知地址hrefbackurlYN下行同步通知过程的返回地址(在支付完成后##联盟接口将会跳转到的商户系统连接地址)。注：若提交值无该参数，或者该参数值为空，则在支付完成后，##联盟接口将不会跳转到商户系统，用户将停留在##联盟接口系统提示支付成功的页面。支付用户IPpayerIpYN用户在下单时的真实IP，##联盟接口将会判断玩家支付时的ip和该值是否相同。若不相同，##联盟接口将提示用户支付风险备注消息attachYN备注信息，下行中会原样返回。若该值包含中文，请注意编码MD5签名signN-32位小写MD5签名值，GB2312编码代理IDagentN代理ID如果没有代理，可以留空4、MD5签名说明待签名数据为表1中加入签名列值为Y的参数以及商户密钥，签名顺序为表1中parter到callbackurl的顺序加商户密钥。具体MD5签名源串及格式如下：parter={}&type={}&value={}&orderid={}&callbackurl={}key其中，key为商户签名。5、接入实例：（假设商户Id为99，商户密钥为1234567890abcd1f）请求提交方法：http://#############/chargebank.aspx?parter=99&type=963&value=100.00&orderid=1234567890&callbackurl==http://######################/notifyAction&payerIp=127.0.0.1&attach=7uka&sign=fde74a4c040b5022cd9c4d9e6b917fcc&agent=1024实际进行MD5加密的串是parter=99&type=963&value=100.00&orderid=1234567890&callbackurl=，该串MD5加密结果为fde74a4c040b5022cd9c4d9e6b917fcc6、特别说明：①在接口使用中，商户系统内发起请求时应使用页面跳转的方式跳转到接口地址。如在jsp中，使用response.sendRedirect(接口地址及参数)，在.net中，使用Response.Redirect(接口地址及参数)。②若hrefbackurl有效，则在跳转返回通知过程中，##联盟接口将使用相同方法跳转回商户系统，跳转地址是hrefbackurl。③根据HTTP协议要求，提交参数的值中若存在特殊字符（如：空格、@等）时，为使##联盟接口能接收到正确的参数，这些特殊字符需要做URLEncoding。需特别注意的是，此时待签名数据应该是原生值而不是encoding之后的值。2、下行异步通知过程接口定义（##联盟接口发起请求）1、接入URL：过程1中请求参数callbackurl值2、接入方式：GET方式3、请求协议参数：表2下行过程请求协议参数说明参数名参数加入签名说明商户订单号orderidY上行过程中商户系统传入的orderid。订单结果opstateY0：支付成功-1请求参数无效-2签名错误订单金额ovalueY订单实际支付金额，单位元MD5签名sign-32位小写MD5签名值，GB2312编码##联盟订单号sysorderidN此次订单过程中##联盟接口系统内的订单Id##联盟订单时间completiontimeN此次订单过程中##联盟接口系统内的订单结束时间。格式为年/月/日时：分：秒，如2010/04/0521:50:58备注信息attachN备注信息，上行中attach原样返回订单结果说明msgN订单结果说明4、返回协议参数：表3下行异步通知返回协议参数参数名参数说明操作结果状态opstate0：处理成功-1：请求参数无效-2：签名错误5、MD5签名说明：待签名数据为表2中加入签名列值为Y的参数以及商户密钥，签名顺序为表2中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：orderid={}&opstate={}&ovalue={}key其中，key