1、接口文档说明示例支付网关说明文档by:Q294500001第一章 文档描述1、文档说明本说明文档用于指导#联盟商户实现与#联盟网银接口的顺利对接。请相关技术人员详细阅读本文档。2、阅读对象商户开发人员。第二章 系统原理1、术语定义商户：指已独立拥有在线销售系统，并成为#联盟网银接口系统会员，且已使用或者将使用#联盟网银接口实现收付费或其他相关功能需求的企业或者个人。外部接入接口：指#联盟通过统一的方式接受外部请求的接口。商户系统：指使用#联盟外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。用户：指在商户系统内进行消费的企业或者个人。商户ID： 指#联盟为使用外部接入接口的商户统一分配
2、的唯一标识。商户密钥：指商户在和#联盟确定合作意向时#联盟为商户提供的16位字符串。该信息作为商户系统和#联盟交互时身份确认的依据，需商户妥善保管。2、消费流程通常，一次支付最少包括2个交互过程。第一个过程是商户系统将在线支付等信息提交到#联盟接口的过程，称之为上行过程。第二个过程是在支付完成后，#联盟接口通过server to server方式将支付结果告知商户系统的过程，称之为下行异步通知过程。如果用户在跳转到#联盟接口完成支付操作后，需要#联盟接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括第三个流程，下行同步通知过程。该过程需要在上行过程中提交
3、参数hrefbackurl。3、查询流程在商户系统将订单成功提交给#联盟接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。4、系统加密#联盟接口采用MD5加密方式对传输数据进行签名验证，具体请参考相关接口定义。对MD5加密后的签名值，请注意结果的大小写务必正确。为了确保签名值不是因为MD5加密算法而导致结果不正确，请各商户在调用接口前对字符串1234567890abcdefghijklmnoprstuvwxyz使用MD5加密算法进行加密，若加密结果为#则表示MD5加密正常。第三章 网银接口定义1、同步过程接口定义（商户系统发起请求）1、接入URL
4、：http:/*/chargebank.aspx (最新地址)2、接入方式：GET方式3、请求协议参数：表1 同步过程请求协议参数说明参数名参数可空加入签名说明商户IDparterNY商户id，由#联盟分配银行类型typeNY银行类型，具体请参考附录1金额valueNY单位元（人民币），2位小数，最小支付金额为0.02商户订单号orderidNY商户系统订单号，该订单号将作为#联盟接口的返回数据。该值需在商户系统内唯一，#联盟系统暂时不检查该值是否唯一下行异步通知地址callbackurlNY下行异步通知过程的返回地址，需要以http:/开头且没有任何参数下行同步通知地址hrefbackurl
5、YN下行同步通知过程的返回地址(在支付完成后#联盟接口将会跳转到的商户系统连接地址)。注：若提交值无该参数，或者该参数值为空，则在支付完成后，#联盟接口将不会跳转到商户系统，用户将停留在#联盟接口系统提示支付成功的页面。支付用户IPpayerIpYN用户在下单时的真实IP，#联盟接口将会判断玩家支付时的ip和该值是否相同。若不相同，#联盟接口将提示用户支付风险备注消息attachYN备注信息，下行中会原样返回。若该值包含中文，请注意编码MD5签名signN-32位小写MD5签名值，GB2312编码代理IDagentN代理ID 如果没有代理，可以留空4、MD5签名说明待签名数据为表1中加入签名列
6、值为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= =127.0.0.1&attach=7uka&sign=fde74a4c040b5022
7、cd9c4d9e6b917fcc&agent=1024实际进行MD5加密的串是parter=99&type=963&value=100.00&orderid=1234567890&callbackurl=fde74a4c040b5022cd9c4d9e6b917fcc6、特别说明：在接口使用中，商户系统内发起请求时应使用页面跳转的方式跳转到接口地址。如在jsp中，使用response.sendRedirect(接口地址及参数)，在.net中，使用Response.Redirect(接口地址及参数)。若hrefbackurl有效，则在跳转返回通知过程中，#联盟接口将使用相同方法跳转回商户系统，跳
8、转地址是hrefbackurl。根据HTTP协议要求，提交参数的值中若存在特殊字符（如：空格、等）时，为使#联盟接口能接收到正确的参数，这些特殊字符需要做URL Encoding。需特别注意的是，此时待签名数据应该是原生值而不是encoding之后的值。2、下行异步通知过程接口定义（#联盟接口发起请求）1、接入URL：过程1中请求参数callbackurl值 2、接入方式：GET方式3、请求协议参数：表2 下行过程请求协议参数说明参数名参数加入签名说明商户订单号orderidY上行过程中商户系统传入的orderid。订单结果opstateY0：支付成功-1 请求参数无效-2 签名错误订单金额o
9、valueY订单实际支付金额，单位元MD5签名sign-32位小写MD5签名值，GB2312编码#联盟订单号sysorderidN此次订单过程中#联盟接口系统内的订单Id#联盟订单时间completiontimeN此次订单过程中#联盟接口系统内的订单结束时间。格式为年/月/日 时：分：秒，如2010/04/05 21:50:58备注信息attachN备注信息，上行中attach原样返回订单结果说明msgN订单结果说明4、返回协议参数：表3 下行异步通知返回协议参数参数名参数说明操作结果状态opstate0：处理成功-1：请求参数无效-2：签名错误5、MD5签名说明：待签名数据为表2中加入签名列
10、值为Y的参数以及商户密钥，签名顺序为表2中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：orderid=&opstate=&ovalue=key其中，key为商户签名。6、特别说明：下行异步通知过程在整个支付流程中一定存在。商户系统在收到下行通知过程后，需向#联盟接口返回类似opstate=0的结果。#联盟接口根据该返回值判断商户系统是否已经收到结果。若返回结果不是opstate=0（可能是opstate=-1、-2或者空），#联盟接口会根据商家和#联盟接口的约定，再次反复向callbackurl发送结果，直到商户返回opstate=0或者达到和商户约定的重复发送
11、次数。当#联盟接口在下行异步通知过程中返回在线支付结果时，商户系统在收到数据后，应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。7、注意事项：在收到#联盟接口订单下行异步通知结果时，商户系统需首先验证订单通知的合法性，如果不合法，则不要更新商户系统上的订单状态。商户系统内订单状态和订单实际金额务必以此次#联盟接口订单异步通知的结果为准。商户系统在成功提交订单后，在未没有收到#联盟接口异步通知结果时，请不要更新商户系统上的订单状态。商户系统收到异步通知结果后，处理流程可表示为：if(返回参数同表2表述不同) 同步返回#联盟接口opstate=-1if(签名正确)
12、if（opstate=0 或者 = -3） 按照成功处理商户系统内订单，订单实际金额为ovalue else 按照失败处理商户系统内订单 同步返回#联盟接口opstate=0else 同步返回#联盟接口opstate=-2在下行异步通知过程中商户系统返回结果值opstate回#联盟接口时，opstate的值并不是将#联盟接口在下行异步通知的结果原样返回。商户系统返回值opstate=0时表示商户系统已经成功接收到了结果（不论结果是什么，总之是收到了），而其他值表示因为某些原因商户系统并不认为#联盟接口的返回是有效的。#联盟接口在收到商户系统的返回后，如果返回的值为opstate=0，#联盟接口
13、将不再次发送结果，否则#联盟接口会根据#联盟接口同商户的约定再次发送结果。3、下行同步通知过程接口定义（#联盟接口发起请求）1、接入URL：过程1中请求参数hrefbackurl值 2、接入方式：GET方式3、请求协议参数：该过程参数同表2所示。4、特别说明：如果用户在跳转到#联盟接口完成支付操作后，需要#联盟接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。当#联盟接口在下行同步通知过程中返回在线支付结果时，商户系统在收到数据后，应该通过sign值判断是否是有效的返回数据，防止数据
14、在网络传输过程中被恶意篡改。第四章 查询流程接口定义1、接入URL：http:/ #/Search.aspx2、接入方式：GET方式3、请求协议参数：表4 查询流程请求协议参数参数名参数加入签名说明商户订单号orderidY需查询的商户系统订单号商户IDparterY商户id，由#联盟分配。MD5签名sign-32位小写MD5签名值，GB2312编码4、返回协议参数表5 查询流程返回协议参数参数名参数加入签名说明商户订单号orderidY请求的商户订单号订单结果opstateY3：请求参数无效2：签名错误1：商户订单号无效0：支付成功 其他：用户还未完成支付或者支付失败订单金额ovalueY订
15、单实际金额，单位元MD5签名sign-32位小写MD5签名值，GB2312编码5、MD5签名说明：查询请求签名：待签名数据为表4中加入签名列值为Y的参数以及商户密钥，签名顺序为表4中orderid到parter的顺序加商户密钥。具体MD5签名源串及格式如下：orderid=&parter=key其中，key为商户签名。查询返回签名：待签名数据为表5中加入签名列值为Y的参数以及商户密钥，签名顺序为表5中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：orderid=&opstate=&ovalue=key其中，key为商户签名。附录1：#联盟支付网关银行类型说明表7
16、#联盟接口银行类型说明 编号类型962中信银行963中国银行964中国农业银行965中国建设银行966中国工商银行（仅限工行手机签约客户）967中国工商银行（全国范围）968浙商银行969浙江稠州商业银行（暂停使用）970招商银行971邮政储蓄972兴业银行973顺德农村信用合作社（暂停使用）974深圳发展银行975上海银行976上海农村商业银行977浦东发展银行978平安银行979南京银行980民生银行981交通银行982华夏银行983杭州银行984广州市农村信用社|广州市商业银行985广东发展银行986光大银行987东亚银行988渤海银行989北京银行990北京农村商业银行992支付宝993财付通994快钱1003支付宝扫码支付211微信扫码支付
