##联盟支付网关说明文档 1
目录 2
第一章 文档描述 3
1、文档说明 3
2、阅读对象 3
第二章 系统原理 3
1、术语定义 3
2、消费流程 3
3、查询流程 4
4、系统加密 4
第三章 网银接口定义 4
1、同步过程接口定义（商户系统发起请求） 4
2、下行异步通知过程接口定义（##联盟接口发起请求） 7
3、下行同步通知过程接口定义（##联盟接口发起请求） 9
第四章 查询流程接口定义 10
第五章 订单外部查询独立网址 11
附录1：##联盟支付网关银行类型说明 12
本说明文档用于指导##联盟商户实现与##联盟网银接口的顺利对接。请相关技术人员详细阅读本文档。
商户开发人员。
商户：指已独立拥有在线销售系统，并成为##联盟网银接口系统会员，且已使用或者将使用##联盟网银接口实现收付费或其他相关功能需求的企业或者个人。
外部接入接口：指##联盟通过统一的方式接受外部请求的接口。
商户系统：指使用##联盟外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。
用户：指在商户系统内进行消费的企业或者个人。
商户ID： 指##联盟为使用外部接入接口的商户统一分配的唯一标识。
商户密钥：指商户在和##联盟确定合作意向时##联盟为商户提供的16位字符串。该信息作为商户系统和##联盟交互时身份确认的依据，需商户妥善保管。
通常，一次支付最少包括2个交互过程。第一个过程是商户系统将在线支付等信息提交到##联盟接口的过程，称之为上行过程。第二个过程是在支付完成后，##联盟接口通过server to server方式将支付结果告知商户系统的过程，称之为下行异步通知过程。
如果用户在跳转到##联盟接口完成支付操作后，需要##联盟接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括第三个流程，下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。
在商户系统将订单成功提交给##联盟接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。
##联盟接口采用MD5加密方式对传输数据进行签名验证，具体请参考相关接口定义。对MD5加密后的签名值，请注意结果的大小写务必正确。
为了确保签名值不是因为MD5加密算法而导致结果不正确，请各商户在调用接口前对字符串1234567890abcdefghijklmnoprstuvwxyz使用MD5加密算法进行加密，若加密结果为##################################则表示MD5加密正常。
1、接入URL：http://************/chargebank.aspx (最新地址)
2、接入方式：GET方式
3、请求协议参数：
表1 同步过程请求协议参数说明
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://www.example.com/backAction&hrefbackurl=http://######################/notifyAction&payerIp =127.0.0.1&attach=7uka&sign=fde74a4c040b5022cd9c4d9e6b917fcc&agent=1024
实际进行MD5加密的串是
parter=99&type=963&value=100.00&orderid=1234567890&callbackurl=http://www.example.com/backAction1234567890abcdef，该串MD5加密结果为
fde74a4c040b5022cd9c4d9e6b917fcc
6、特别说明：
在接口使用中，商户系统内发起请求时应使用页面跳转的方式跳转到接口地址。如在jsp中，使用response.sendRedirect(接口地址及参数)，在.net中，使用Response.Redirect(接口地址及参数)。
若hrefbackurl有效，则在跳转返回通知过程中，##联盟接口将使用相同方法跳转回商户系统，跳转地址是hrefbackurl。
根据HTTP协议要求，提交参数的值中若存在特殊字符（如：空格、@等）时，为使##联盟接口能接收到正确的参数，这些特殊字符需要做URL Encoding。需特别注意的是，此时待签名数据应该是原生值而不是encoding之后的值。
1、接入URL：过程1中请求参数callbackurl值
2、接入方式：GET方式
3、请求协议参数：
表2 下行过程请求协议参数说明
4、返回协议参数：
表3 下行异步通知返回协议参数
5、MD5签名说明：
待签名数据为表2中加入签名列值为Y的参数以及商户密钥，签名顺序为表2中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：
orderid={}&opstate={}&ovalue={}key
其中，key为商户签名。
6、特别说明：
下行异步通知过程在整个支付流程中一定存在。商户系统在收到下行通知过程后，需向##联盟接口返回类似opstate=0的结果。##联盟接口根据该返回值判断商户系统是否已经收到结果。若返回结果不是opstate=0（可能是opstate=-1、-2或者空），##联盟接口会根据商家和##联盟接口的约定，再次反复向callbackurl发送结果，直到商户返回opstate=0或者达到和商户约定的重复发送次数。
当##联盟接口在下行异步通知过程中返回在线支付结果时，商户系统在收到数据后，应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。
7、注意事项：
在收到##联盟接口订单下行异步通知结果时，商户系统需首先验证订单通知的合法性，如果不合法，则不要更新商户系统上的订单状态。
商户系统内订单状态和订单实际金额务必以此次##联盟接口订单异步通知的结果为准。
商户系统在成功提交订单后，在未没有收到##联盟接口异步通知结果时，请不要更新商户系统上的订单状态。
商户系统收到异步通知结果后，处理流程可表示为：
if(返回参数同表2表述不同)
同步返回##联盟接口opstate=-1
if(签名正确)｛
if（opstate==0 或者 == -3）｛
按照成功处理商户系统内订单，订单实际金额为ovalue
｝else｛
按照失败处理商户系统内订单
｝
同步返回##联盟接口opstate=0
｝else{
同步返回##联盟接口opstate=-2
}
在下行异步通知过程中商户系统返回结果值opstate回##联盟接口时，opstate的值并不是将##联盟接口在下行异步通知的结果原样返回。商户系统返回值opstate=0时表示商户系统已经成功接收到了结果（不论结果是什么，总之是收到了），而其他值表示因为某些原因商户系统并不认为##联盟接口的返回是有效的。##联盟接口在收到商户系统的返回后，如果返回的值为opstate=0，##联盟接口将不再次发送结果，否则##联盟接口会根据##联盟接口同商户的约定再次发送结果。
1、接入URL：过程1中请求参数hrefbackurl值
2、接入方式：GET方式
3、请求协议参数：
该过程参数同表2所示。
4、特别说明：
如果用户在跳转到##联盟接口完成支付操作后，需要##联盟接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。
当##联盟接口在下行同步通知过程中返回在线支付结果时，商户系统在收到数据后，应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。
1、接入URL：http:// ############/Search.aspx
2、接入方式：GET方式
3、请求协议参数：
表4 查询流程请求协议参数
4、返回协议参数
表5 查询流程返回协议参数
5、MD5签名说明：
查询请求签名：
待签名数据为表4中加入签名列值为Y的参数以及商户密钥，签名顺序为表4中orderid到parter的顺序加商户密钥。具体MD5签名源串及格式如下：
orderid={}&parter={}key
其中，key为商户签名。
查询返回签名：
待签名数据为表5中加入签名列值为Y的参数以及商户密钥，签名顺序为表5中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：
orderid={}&opstate={}&ovalue={}key
其中，key为商户签名。
表7 ##联盟接口银行类型说明
本文来源：https://www.2haoxitong.net/k/doc/e51eac83f5335a8103d22013.html
文档为doc格式