接口文档说明示例.docx
《接口文档说明示例.docx》由会员分享，可在线阅读，更多相关《接口文档说明示例.docx（11页珍藏版）》请在冰豆网上搜索。
接口文档说明示例
支付网关说明文档by:
Q294500001
第一章文档描述
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同步过程请求协议参数说明
参数名
参数
可空
加入签名
说明
商户ID
parter
N
Y
商户id，由##联盟分配
银行类型
type
N
Y
银行类型，具体请参考附录1
金额
value
N
Y
单位元（人民币），2位小数，最小支付金额为0.02
商户订单号
orderid
N
Y
商户系统订单号，该订单号将作为##联盟接口的返回数据。
该值需在商户系统内唯一，##联盟系统暂时不检查该值是否唯一
下行异步通知地址
callbackurl
N
Y
下行异步通知过程的返回地址，需要以http:
//开头且没有任何参数
下行同步通知地址
hrefbackurl
Y
N
下行同步通知过程的返回地址（在支付完成后##联盟接口将会跳转到的商户系统连接地址）。
注：
若提交值无该参数，或者该参数值为空，则在支付完成后，##联盟接口将不会跳转到商户系统，用户将停留在##联盟接口系统提示支付成功的页面。
支付用户IP
payerIp
Y
N
用户在下单时的真实IP，##联盟接口将会判断玩家支付时的ip和该值是否相同。
若不相同，##联盟接口将提示用户支付风险
备注消息
attach
Y
N
备注信息，下行中会原样返回。
若该值包含中文，请注意编码
MD5签名
sign
N
-
32位小写MD5签名值，GB2312编码
代理ID
agent
N
代理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==127.0.0.1&attach=7uka&sign=fde74a4c040b5022cd9c4d9e6b917fcc&agent=1024
实际进行MD5加密的串是
parter=99&type=963&value=100.00&orderid=1234567890&callbackurl=
fde74a4c040b5022cd9c4d9e6b917fcc
6、特别说明：
在接口使用中，商户系统内发起请求时应使用页面跳转的方式跳转到接口地址。
如在jsp中，使用response.sendRedirect（接口地址及参数），在.net中，使用Response.Redirect（接口地址及参数）。
若hrefbackurl有效，则在跳转返回通知过程中，##联盟接口将使用相同方法跳转回商户系统，跳转地址是hrefbackurl。
根据HTTP协议要求，提交参数的值中若存在特殊字符（如：
空格、@等）时，为使##联盟接口能接收到正确的参数，这些特殊字符需要做URLEncoding。
需特别注意的是，此时待签名数据应该是原生值而不是encoding之后的值。
2、下行异步通知过程接口定义（##联盟接口发起请求）
1、接入URL：
过程1中请求参数callbackurl值
2、接入方式：
GET方式
3、请求协议参数：
表2下行过程请求协议参数说明
参数名
参数
加入签名
说明
商户订单号
orderid
Y
上行过程中商户系统传入的orderid。
订单结果
opstate
Y
0：
支付成功
-1请求参数无效
-2签名错误
订单金额
ovalue
Y
订单实际支付金额，单位元
MD5签名
sign
-
32位小写MD5签名值，GB2312编码
##联盟订单号
sysorderid
N
此次订单过程中##联盟接口系统内的订单Id
##联盟订单时间
completiontime
N
此次订单过程中##联盟接口系统内的订单结束时间。
格式为
年/月/日时：
分：
秒，如2010/04/0521:
50:
58
备注信息
attach
N
备注信息，上行中attach原样返回
订单结果说明
msg
N
订单结果说明
4、返回协议参数：
表3下行异步通知返回协议参数
参数名
参数
说明
操作结果状态
opstate
0：
处理成功
-1：
请求参数无效
-2：
签名错误
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，##联盟接口将不再次发送结果，否则##联盟接口会根据##联盟接口同商户的约定再次发送结果。
3、下行同步通知过程接口定义（##联盟接口发起请求）
1、接入URL：
过程1中请求参数hrefbackurl值
2、接入方式：
GET方式
3、请求协议参数：
该过程参数同表2所示。
4、特别说明：
如果用户在跳转到##联盟接口完成支付操作后，需要##联盟接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括下行同步通知过程。
该过程需要在上行过程中提交参数hrefbackurl。
当##联盟接口在下行同步通知过程中返回在线支付结果时，商户系统在收到数据后，应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。
第四章查询流程接口定义
1、接入URL：
http:
//############/Search.aspx
2、接入方式：
GET方式
3、请求协议参数：
表4查询流程请求协议参数
参数名
参数
加入签名
说明
商户订单号
orderid
Y
需查询的商户系统订单号
商户ID
parter
Y
商户id，由##联盟分配。
MD5签名
sign
-
32位小写MD5签名值，GB2312编码
4、返回协议参数
表5查询流程返回协议参数
参数名
参数
加入签名
说明
商户订单号
orderid
Y
请求的商户订单号
订单结果
opstate
Y
3：
请求参数无效
2：
签名错误
1：
商户订单号无效
0：
支付成功
其他：
用户还未完成支付或者支付失败
订单金额
ovalue
Y
订单实际金额，单位元
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##联盟接口银行类型说明
编号
类型
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
微信扫码支付
升级会员 