标准快速付款接口文档

目录

1.引言 (3)

1.1.文档概述 (3)

1.2.业务术语 (3)

2.交互模式 (3)

2.1.请求/响应交互模式 (3)

2.1.1.处理流程 (4)

2.2.主动通知交互模式 (4)

2.2.1.处理流程 (5)

2.2.2.通知验证 (6)

3.安全规范 (7)

3.1.数字签名 (7)

3.1.1.签名机制 (8)

3.1.2.签名方式 (8)

4.接口 (9)

4.1.外部接入接口 (9)

4.1.1.业务功能 (9)

4.1.2.请求参数列表 (9)

4.2.外部通知接口 (12)

4.2.1.通知返回参数列表 (12)

4.2.2.交易状态枚举表 (13)

4.2.3.退款状态枚举表 (14)

4.2.4.银行列表 (14)

4.2.5.错误代码列表 (14)

4.3.通知返回的区别（return_url和notify_url） (16)

5.应用场景 (17)

5.1.场景描述 (17)

5.1.1.交易流程图例 (18)

5.2.交互实例 (18)

5.2.1.产生待签名数据 (19)

5.2.2.计算sign值 (19)

5.2.3.商户系统发起请求 (20)

5.2.4.支付宝系统返回处理结果 (20)

5.3.通知返回结果枚举表 (20)

5.4.签名及加密算法 (21)

5.4.1.签名算法对比 (21)

5.4.2.MD5签名算法 (21)

5.4.3.DSA签名算法 (21)

5.4.4.RSA签名算法 (22)

5.5.OpenSSL命令 (22)

5.5.1.DSA密钥生成命令 (22)

5.5.2.RSA密钥生成命令 (22)

5.5.3.签名/验签名命令 (22)

1.引言

1.1.文档概述

支付宝对外接口分为两种，一种是接收外部请求的接口，我们统称为外部接入接口。一种是主动通知外部系统的接口，我们统称为外部通知接口。

外部服务接口的主要目的是让外部合作伙伴主动使用我们的服务，如：创建交易等。外部通知接口的主要目的是为外部合作伙伴提供数据同步服务（如：交易状态同步）以及异步处理结果返回服务（有些业务的处理是无法做到即时返回的）。

阅读对象：商户系统（商户）的技术开发人员。

1.2.业务术语

2.交互模式

2.1.请求/响应交互模式

请求/响应模式是最常用的一种交互模式。在这种交互模式下，商户系统向支付宝系统发送请求数据，并同步等待支付宝系统处理完毕之后返回的响应数据。

请求/响应模式根据页面流程，可以分为系统调用和页面跳转，系统调用只

需要调用相关接口文件就可以完成相关的业务操作，而页面跳转则需要进入支付宝系统的页面，完成相关操作。

如果买家在跳转到支付宝页面完成相关操作之后，需要支付宝系统将处理结果立即返回给商户网站的下一步操作页面，让用户继续完成整个操作流程，必须传递参数return_url （即进入商户系统的下一个操作页面）。

2.1.1. 处理流程

接入URL

：

2.2. 主动通知交互模式

买家从商户网站跳转到支付宝网站，在支付宝网站完成最后操作，买家不用再回到商户网站。支付宝单系统会将商户关注的事件采用主动通知的方式提交给商户系统。

这种交互模式如果需要异步返回结果，必须传递notify_url参数，以指定通知返回的地址；如果不需要异步返回结果，那么可以不用传递notify_url参数。

例如，通过商户系统创建交易，当交易状态（参见：交易状态枚举表）发生改变时，支付宝系统将最新的交易状态以及其它交易有关的信息主动通知给商户系统，达到使双方的系统业务联动的目的。

2.2.1.处理流程

1.支付宝系统向商户系统发出通知，即访问商户提供的通知接收URL（参数

notify_url）。

2.商户系统接到通知请求，通过notify_id询问支付宝系统这个通知的真实性,

通知验证。

3.支付宝系统判断通知是否是自己发送，如果是返回true，否则返回false。

4.商户系统得到支付宝系统的确认后，对通知进行处理。处理完毕后，返回结

果给支付宝系统，处理结果的值见附件：通知返回结果枚举表。

5.支付宝系统处理商户系统返回的处理结果。

支付宝系统是通过HTTP/HTTPS协议的POST方法将通知数据发送给商户系统的。商户系统的通知URL可以在合作协议中静态配置,则针对该笔交易的所有事件的主动通知，支付宝系统都会通过该notify_url发送给商户系统。

如果支付宝系统发送通知数据不成功，或者没有收到商户系统处理成功的响应，则支付宝系统会按照一定的重试策略(1分钟、3分钟、5分钟、10分钟。。。。)，定期重新发送主动通知，以提高主动通知消息的到达率。但支付宝单系统不保证所有的主动通知消息一定能够送达。

由于存在重新发送主动通知的情况，因此同样的通知可能会多次发送给商户系统，而且业务上存在先后的事务的主动通知，并不一定按照正确的次序发送。商户系统必须能够正确忽略重复的主动通知，并能正确处理通知次序颠倒的情况。支付宝系统推荐的做法是，当收到通知并进行处理时，需要检查本系统内对应业务数据的状态，以判断该主动通知是否已经处理过，或者主动通知对应的事件次序是否正确。在对业务数据进行状态检查与处理之前，要求采用数据锁或者时间戳判断进行并发控制。

2.2.2.通知验证

从系统健康性角度考虑，在接收到支付宝系统通知以后，验证支付宝系统通知的正确性（合法性）是非常有必要的。强烈建议商户系统加入此应用。为了保证该接口被合法利用，商户系统只能查找1分钟之内（目前为1分钟，以后若有调整，恕不另行通知）的通知。

? 基于HTTPS 协议的通知验证接口

程序在使用时按照以下要求发起一个HTTPS 请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表，这种验证通知的方式需要网站支持HTTPS 访问，若网站不支持https 的访问，可以使用另外一种验证方式：基于HTTP 协议的通知验证接口。

接入URL

：

一个完整的验证请求实例：

https://https://www.wendangku.net/doc/572616801.html,/cooperate/gateway.do?service=notify_ve

rify&partner=1234567890¬ify_id=abcdefghijklmnopqrst

? 基于HTTP 协议的通知验证接口

程序在使用时按照以下要求发起一个HTTP 请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表。

接入URL

：

一个完整的验证请求实例：

https://www.wendangku.net/doc/572616801.html,/trade/notify_query.do?partner=1234567890¬ify_id=abcdefghijklmnopqrst

通知验证接口输出参数：

3. 安全规范

3.1. 数字签名

数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，

在接收签名数据之后进行签名校验。

3.1.1.签名机制

待签名数据是请求参数按照以下方式组装成的字符串：

?请求参数按照参数名字符升序排列，如果有重复参数名，那么重复的参数再按照参

数值的字符升序排列。

?所有参数（除了sign和sign_type）按照上面的排序用&连接起来，格式是：

p1=v1&p2=v2。

调用某接口需要以下参数：

service=create_direct_pay_by_user,partner=20880063000,email=test@ https://www.wendangku.net/doc/572616801.html,

那么待签名数据就是：

email=test@https://www.wendangku.net/doc/572616801.html,&partner=20880063000&service=create_direct_pay_ by_user

注意事项：

?没有值的参数无需传递，也无需包含到待签名数据中。

?签名时将字符转化成字节流时指定的字符集与_input_charset保持一致。

?如果传递了_input_charset参数，这个参数也应该包含在待签名数据中。

?根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、@等），那么该值

需要做URL Encoding，这样请求接收方才能接收到正确的参数值。这种情况下，待签名数据应该是原生值而不是encoding之后的值。例如：调用某接口需要对请求参数email进行数字签名，那么待签名数据应该是：email=test@https://www.wendangku.net/doc/572616801.html,，而不是email=test%https://www.wendangku.net/doc/572616801.html,。

3.1.2.签名方式

按照sign_type参数指定的签名算法对待签名数据进行签名。（参见：签名及加密算法）

4.接口

4.1.外部接入接口

4.1.1.业务功能

调用此接口，根据用户传过来的参数创建交易，买家再付款。目前该接口的交易全部为即时到帐，即只要买家一付款，钱就会转到卖家的支付宝账号上。同时该接口还支持分润，商家传过来分润的账号和金额，系统会自动打款到该账号上。

交互模式

请求/响应交互模式，页面跳转

4.1.2.请求参数列表

注意：只有按照支付宝交易服务接口规范中制定的签名机制，对请求参数进行签名，才能够被支付宝系统接收。

一个完整的支付接入请求实例：

4.2.外部通知接口

4.2.1.通知返回参数列表

注意：只有在跳转页面中输入正确登陆密码支付密码后才能创建交易和通知返回

1. 合作伙伴通过“标准快速付款”接口创建交易时，如果在参数中传递了notify_url，那么当该交易的通知触发条件发生改变时，支付宝会向合作伙伴发送同步通知。

从集成后的系统健壮性考虑，收到支付宝发出的通知后，合作伙伴系统须判断接收到的交易状态是否与自己系统中的参数对应。如果不判断，存在潜在的风险，合作伙伴自行承担因此而产生的所有损失。

4.2.2.交易状态枚举表

4.2.3.退款状态枚举表

4.2.4.银行列表

4.2.

5.错误代码列表

4.3.通知返回的区别（return_url和notify_url）

return_url：客户端返回

支付完成后立刻返回到商户网站的客户端上，是可见的，返回机制：以GET 的方式返回，返回信息包括提交给支付宝的订单信息，可根据这个返回信息做相应的操作显示给客户看。

notify_url：服务器的返回

服务器的通知返回是由支付宝的服务器发起，以POST的方式返回到商户的网站上。返回信息包括提交给支付宝的订单信息，在返回的文件中，注意需要输出success做为支付宝通知返回信息成功，若没有这个success的输出，那么支付宝的服务器会在交易产生后的24小时内返回支付订单信息，返回的时间频率会逐渐减弱，（1分钟、3分钟、5分钟、10分钟、15。。。。。。。。。。）

1、notify_url 页面中只能做对数据库的业务操作。return_url的返回页面中也可以做数据库的更新也可以做显示。

2、return_url和notify_url 可以都设置，一个做数据显示，一个做更新数

据库

建议，做接口测试的时候，首先获得对应的Demo代码后，返回页面写好您的合作id和Key的信息后进行测试，确定没有问题再添加对数据库更改的操作语句。

获得此交易状态方式(交易状态枚举表)：例如asp编程语言中：

notify_url 页面request.Form("trade_status")

return_url页面request("trade_status") 其它相对信息也是以此方式获得5.应用场景

5.1.场景描述

商户买家NaNa有一个支付宝账户，想在商户的网站购买一张游戏点卡，很快他选择了一张50元面值的游戏点卡，在商户网站上下订单进行购买，并选择支付宝支付方式付款。

NaNa选择支付宝方式付款后，商户系统调用支付宝系统的支付接入接口（参见：支付接入接口），从商户网站跳转到支付宝的页面，NaNa输入支付宝账户和支付密码开始付款，如果她的支付宝帐户有足够这笔交易的余额，那么她可以迅速完成交易付款；如果他的支付宝账户没有足够这笔交易的余额，她可以选择网银付款或者支付宝的卡通产品付款。

NaNa支付成功后，支付宝系统向商户系统发送交易信息的通知，商户系统在接收到通知之后（参见：外部通知接口，向支付宝系统发送通知验证请求（参见：通知验证），判断该通知的合法性和真实性。支付宝系统验证通知，并返回验证结果。如果验证结果为true，商户系统根据该通知做相应的处理，比如给买家NaNa的账户中发送卡密）。处理完毕，返回结果给支付宝系统(输出success)。

商户还可以根据NaNa本次交易的外部交易号（out_trade_no）查询商户网

站内的相关交易信息，判断NaNa是否是此订单，确认正确后，商户就可以开始给NaNa的游戏账户发送卡密或游戏币。

此时买家的货款就会自动到卖家的账户上。

5.1.1.交易流程图例

5.2.交互实例

买家在商户网站拍下商品后，选择支付宝方式付款，商户系统调用支付宝支付接入接口，根据请求参数的格式，我们给出如下例子：

假设使用MD5签名算法，并且签名密钥是abc123，即请求参数sign_type=MD5。

5.2.1.产生待签名数据

根据签名机制，我们首先对请求参数进行排序，结果如下：

使用“&”符号把参数串联起来，产生待签名数据：

5.2.2.计算sign值

这个实例我们前面已经假设使用MD5签名算法，并且给出签名密钥为abc123，那么在计算sign值之前，就需要在待签名数据的后边加上签名密钥，即最终的待签名数据如下：

根据请求参数sign_type来判断使用哪种签名算法，这里我们采用MD5签名算法，最终计算出来，sign=275e8da3612b06ab01030f180ca6253d 5.2.3.商户系统发起请求

根据请求/响应交互模式处理流程的支付宝系统服务接入URL，我们按照以下URL发起请求，请求参数的顺序不作要求：

5.2.4.支付宝系统返回处理结果

支付宝系统接收到商户系统发起的请求，处理成功后返回的参数中同样包含有参数sign、sign_type，商户需根据sign_type计算sign值，最终检验支付宝系统返回的sign值，这里要注意的是商户需要对每一个返回参数的值先进行decode后再验证sign。

附录

5.3.通知返回结果枚举表