快付宝API支付平台,网银在线支付接口文档说明

版本: 3.2

发布日期: 2013-5-1

目录

第一章 文档描述    3

1、文档说明    3

2、阅读对象    3

第二章 系统原理    3

1、术语定义    3

2、消费流程    3

3、查询流程    4

4、系统加密    4

第三章 网银接口定义    4

1、上行过程接口定义（商户系统发起请求）    4

2、下行异步通知过程接口定义（快付宝接口发起请求）    7

3、下行同步通知过程接口定义（快付宝接口发起请求）    9

第四章 查询流程接口定义    10

第五章 订单外部查询网址    11

第六章 测试    11

附录1：快付宝网银接口银行类型说明    11

第一章 文档描述

1、文档说明

本说明文档用于指导快付宝商户实现与快付宝网银接口的顺利对接。请相关技术人员详细阅读本文档。

2、阅读对象

商户开发人员。

第二章 系统原理

1、术语定义

商户：指已拥有在线销售系统，并成为快付宝网银接口系统会员，且已使用或者将使用快付宝网银接口实现收付费或其他相关功能需求的企业或者个人。

外部接入接口：指快付宝通过统一的方式接受外部请求的接口。

商户系统：指使用快付宝外部接入接口的计算机系统，一般指商户所拥有的在线销售系统。

用户：指在商户系统内进行消费的企业或者个人。

商户ID： 指快付宝为使用外部接入接口的商户统一分配的唯一标识。

商户密钥：指商户在和快付宝确定合作意向时快付宝为商户提供的16位字符串。该信息作为商户系统和快付宝交互时身份确认的依据，需商户妥善保管。

2、消费流程

通常，一次支付最少包括2个交互过程。第一个过程是商户系统将在线支付等信息提交到快付宝接口的过程，称之为上行过程。第二个过程是在支付完成后，快付宝接口通过server to server方式将支付结果告知商户系统的过程，称之为下行异步通知过程。

如果用户在跳转到快付宝接口完成支付操作后，需要快付宝接口将处理结果立即返回给商户系统的下一步页面，让用户继续完成整个操作流程，此时支付还应包括第三个流程，下行同步通知过程。该过程需要在上行过程中提交参数hrefbackurl。

3、查询流程

在商户系统将订单成功提交给快付宝接口后的任意时间，商户系统可发起请求查询订单的处理结果。该流程由商户系统发起，由接口返回相应结果。

4、系统加密

快付宝接口采用MD5加密方式对传输数据进行签名验证，具体请参考相关接口定义。对MD5加密后的签名值，请注意结果的大小写务必正确。

为了确保签名值不是因为MD5加密算法而导致结果不正确，请各商户在调用接口前对字符串12345670abcdefghijklmnopqrstuvwxyz使用MD5加密算法进行加密，若加密结果为928f7bcdcd08869cc44c1bf24e7abec6则表示MD5加密正常。

第三章 网银接口定义

1、上行过程接口定义（商户系统发起请求）

1、接入URL：http://way.xunjiepay.com/bank.aspx

2、接入方式：GET方式

3、请求协议参数：

表1 上行过程请求协议参数说明

待签名数据为表1中加入签名列值为Y的参数以及商户密钥，签名顺序为表1中parter到callbackurl的顺序加商户密钥。具体MD5签名源串及格式如下：

parter={}&type={}&value={}&orderid ={}&callbackurl={}key

其中，key为商户签名。

5、接入实例：（假设商户Id为99，商户密钥为12345670abcdef）

请求提交方法：

http://way.xunjiepay.com/bank.aspx?parter=99&type=963&value=100.00&orderid=12345670&callbackurl=http://www.xunjiepay.com/backAction&refbackurl=http://www.xunjiepay.com/notifyAction&payerIp =127.0.0.1&attach=ekapay&sign=fde74a4c040b5022cd9c4d9e6b917fcc

实际进行MD5加密的串是

parter=99&type=963&value=100.00&orderid=12345670&callbackurl=http://www.xunjiepay.com/backAction12345670abcdef，该串MD5加密结果为

fde74a4c040b5022cd9c4d9e6b917fcc

6、特别说明：

在接口使用中，商户系统内发起请求时应使用页面跳转的方式跳转到接口地址。如在jsp中，使用response.sendRedirect(接口地址及参数)，在.net中，使用Response.Redirect(接口地址及参数)。

若hrefbackurl有效，则在跳转返回通知过程中，快付宝接口将使用相同方法跳转回商户系统，跳转地址是hrefbackurl。

根据HTTP协议要求，提交参数的值中若存在特殊字符（如：空格、@等）时，为使快付宝接口能接收到正确的参数，这些特殊字符需要做URL Encoding。需特别注意的是，此时待签名数据应该是原生值而不是encoding之后的值。

2、下行异步通知过程接口定义（快付宝接口发起请求）

1、接入URL：过程1中请求参数callbackurl值

2、接入方式：GET方式

3、请求协议参数：

表2 下行过程请求协议参数说明

表3 下行异步通知返回协议参数

待签名数据为表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://way.xunjiepay.com/search.aspx

2、接入方式：GET方式

3、请求协议参数：

表4 查询流程请求协议参数

表5 查询流程返回协议参数

查询请求签名：

待签名数据为表4中加入签名列值为Y的参数以及商户密钥，签名顺序为表4中orderid到parter的顺序加商户密钥。具体MD5签名源串及格式如下：

orderid={}&parter={}key

其中，key为商户签名。

查询返回签名：

待签名数据为表5中加入签名列值为Y的参数以及商户密钥，签名顺序为表5中orderid到ovalue的顺序加商户密钥。具体MD5签名源串及格式如下：

orderid={}&opstate={}&ovalue={}key

其中，key为商户签名。

附录1：快付宝网银接口银行类型说明

表7 快付宝银行类型说明