第三方应用授权更新时间：2020-01-09

概述

通过第三方应用授权，ISV/开发者可以在取得商户授权后，ISV/开发者可以帮助商户完成相应的业务逻辑（如代替商户发起当面付的收单请求等）。

授权采用标准的 OAuth 2.0 流程。要进行第三方调用，ISV/开发者需要在自己的应用中添加对应功能并获得商户授权；商户需要申请开通相应的产品功能。例如对于当面付功能，商户需要先开通“当面付”产品，之后开发者只需在应用中添加“当面付”功能并获得商户授权，就可以帮助商户发起当面付的收单请求。

根据业务场景需要，第三方应用授权分为批量授权和单个授权，两种授权方式的授权流程一致，区别仅在于URL的拼接规则不同，并且单个授权只能获取一个授权令牌 access_token，而批量授权能够同时获取多个授权令牌access_token。

注意：

针对无需签约的功能（使用条件可在应用详情页的功能信息页查看），只需要开发者在应用中添加对应功能，并获得商户授权即可（例如“支付宝卡包”和“商户会员卡”）。

授权流程

第三方应用授权的流程如下图所示：

快速接入

第一步：创建应用

要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（open.alipay.com），在开发者中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限，通过 APPID 您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步：配置密钥

开发者调用接口前需要先生成 RSA 密钥，RSA 密钥包含应用私钥（APP_PRIVATE_KEY）、应用公钥（APP_PUBLIC_KEY）。生成密钥后在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步：应用授权 URL 拼装

拼接规则

单个授权URL拼接规则

https://openauth.alipay.com/oauth2/appToAppAuth.htm?app_id=2015101400446982&redirect_uri=http%3A%2F%2Fexample.com

TIPS：沙箱拼接规则详见下文的“关于沙箱”部份。

参数	参数名称	类型	必填	描述	范例
app_id	开发者应用的AppId	String	是	开发者应用的AppId	2015101400446982
redirect_uri	回调页面	String	是	参数需要UrlEncode	http%3A%2F%2Fexample.com

批量授权URL拼接规则

https://openauth.alipay.com/oauth2/appToAppBatchAuth.htm?app_id=2015101400446982&application_type=TINYAPP,WEBAPP&redirect_uri=http://www.baidu.com

TIPS：沙箱拼接规则详见下文的“关于沙箱”章节。

参数说明

参数	名称	类型	必填	描述
app_id	开发者应用的 AppId	String	是	开发者应用的 AppId
application_type	应用类型	String	是	开发者应用的 AppId 允许的应用类型，支持多个组合，组合格式(中间使用,号分隔)，目前支持类型 MOBILEAPP (移动应用)，WEBAPP（网页应用），PUBLICAPP（生活号），TINYAPP（小程序），ARAPP（AR应用）
redirect_uri	回调页面	String	是	参数需要 UrlEncode
state	商户自定义参数	String	否	state 对应的值必须为 base64 编码

注意：

授权链接中配置的 redirect_uri 内容需要与应用中配置的授权回调地址完全一样，否则无法正常授权。
在授权过程中，建议在拼接授权 URL 的时候，开发者可增加自己的一个自定义信息（即 URL 拼接规则中的 state 参数），便于开发者识别是哪个商户的授权。

使用场景

单个授权场景举例

商户使用开发者提供的应用授权链接在PC端进行应用授权

商户使用开发者提供的应用授权链接在手机端进行应用授权

注：H5授权页只能在支付宝钱包里使用，否则会报错，如下：

批量授权场景举例

PC 端

商户使用开发者提供的应用授权链接在 PC 端进行应用授权，商户可以选择名下应用进行授权。

手机端

商户使用开发者提供的应用授权链接在手机端进行应用授权，商户可以选择名下应用进行授权。

注意：授权页只能在支付宝钱包里使用，否则会报错，如下图所示：

第四步：获取 app_auth_code

商户授权成功后，PC 或者钱包客户端会跳转至开发者定义的回调页面（即 redirect_uri 参数对应的 url ），在回调页面请求中会带上当次授权的授权码 app_auth_code 和开发者的 app_id，示例如下：

http://example.com/doc/toAuthPage.html?app_id=2015101400446982&app_auth_code=ca34ea491e7146cc87d25fca24c4cD11

第五步：使用 app_auth_code 换取 app_auth_token

获取商户信息

接口名称：alipay.open.auth.token.app

开发者通过 app_auth_code 可以 单个/批量 换取 app_auth_token、授权商户的 userId 以及授权商户 AppId。

注意：

应用授权的 app_auth_code 是唯一的；app_auth_code 使用一次后失效，单个授权的有效期为一天（从生成 app_auth_code 开始的24小时）未被使用自动过期；批量授权的有效期为 10 分钟。

app_auth_token 永久有效。

请求参数说明

参数	名称	类型	必填	描述
grant_type	换码类型	String	是	authorization_code：使用 auth_code 换取令牌； refresh_token：使用刷新刷新令牌
code	授权码	String	否	grant_type= authorization_code 时，必须录入
refresh_token	刷新令牌	String	否	grant_type=refresh_toke 时必录

获取授权令牌

下文说明如何使用 alipay.open.auth.token.app 接口换取授权令牌 access_token。

接口请求示例（grant_type=authorization_code）: 请先阅读 SDK 接入说明。

AlipayClientalipayClient = newDefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID,APP_PRIVATE_KEY, 
"json", CHARSET, ALIPAY_PUBLIC_KEY,"RSA2"); 
AlipayOpenAuthTokenAppRequest request = newAlipayOpenAuthTokenAppRequest(); 
request.setBizContent(
    "{" +"\"grant_type\":\"authorization_code\"," +"    
\"code\":\"1cc19911172e4f8aaa509c8fb5d12F56\""+ " 
    }");
AlipayOpenAuthTokenAppResponse response =alipayClient.execute(request);

同步响应参数说明

参数	名称	类型	必填	描述
code	错误码	String	是	错误码
msg	消息	String	是	错误消息
tokens	授权令牌列表	String	是	具体格式参考 “tokens 对应的value值说明”

tokens 对应的 value 值说明

参数	名称	类型	必填	描述
app_auth_token	令牌信息	String	是	授权令牌信息
app_refresh_token	刷新令牌	String	是	刷新令牌
auth_app_id	授权方应用id	String	是	授权方应用 id
expires_in	令牌有效期	String	是	有效期
re_expires_in	刷新令牌有效时间	String	是	刷新令牌有效期
userid	支付宝用户标识	String	是	支付宝用户标识

同步响应结果示例

Tips：单个授权通过 alipay.open.auth.token.app 接口只能换取一个授权令牌access_token,批量授权能换取多个授权令牌access_token，如下为批量授权情况下的结果示例。

{"alipay_open_auth_token_app_response":{
“code”:”10000”,
“msg”:”Success”,
"tokens":[
{
"app_auth_token":"201712BB_D0804adb2e743078d1822d536956X34",
"app_refresh_token":"201712BB_d5b15d53f7b4fd5aa649f176ca97X34",
"auth_app_id": "2017120501354689",
"expires_in": 31536000,
"re_expires_in": 32140800,
"user_id": "2088302181262340"
},
{
"app_auth_token":"201712BB_D0d8c15dc7e4c9dba5e5767b3b37X34",
"app_refresh_token":"201712BB_d96f65e20c745c3998a8452baae5X34",
"auth_app_id": "2017120501354690",
"expires_in": 31536000,
"re_expires_in": 32140800,
"user_id": "2088302181262340"
},
{
"app_auth_token":"201712BB_D335c7b153345a9915a851cf9bd9X34",
"app_refresh_token":"201712BB_ddeeb32d9d145948a488b1058e08X34",
"auth_app_id": "2017120501354688",
"expires_in": 31536000,
"re_expires_in": 32140800,
"user_id": "2088302181262340"
}
]
},     "sign":"TR5xJkWX65vRjwnNNic5n228DFuXGFOCW4isWxx5iLN8EuHoU2OTOeh1SOzRredhnJ6G9eOXFMxHWl7066KQqtyxVq2PvW9jm94QOuvx3TZu7yFcEhiGvAuDSZXcZ0sw4TyQU9+/cvo0JKt4m1M91/Quq+QLOf+NSwJWaiJFZ9k="}

刷新授权令牌

通过接口 alipay.open.auth.token.app 刷新授权令牌 access_token。

接口请求示例（grant_type=refresh_token）: 请先阅读 SDK 接入说明

AlipayClientalipayClient = newDefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID,APP_PRIVATE_KEY, 
"json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");AlipayOpenAuthTokenAppRequest request = new 
AlipayOpenAuthTokenAppRequest();request.setBizContent("{" + "\"grant_type\":\"refresh_token \"," +"    \"
refresh_token\":\"201509BBdcba1e3347de4e75ba3fed2c9abebE36\"" + "  }");AlipayOpenAuthTokenAppResponse 
response = alipayClient.execute(request);

同步响应参数说明

参数	名称	类型	必填	描述
code	消息码	String	是	错误码
msg	消息	String	是	错误消息
app_auth_token	令牌信息	String	是	授权令牌信息
app_refresh_token	刷新令牌	String	是	刷新令牌
auth_app_id	授权方应用id	String	是	授权方应用 id
expires_in	令牌有效期	String	是	有效期
re_expires_in	刷新令牌有效时间	String	是	刷新令牌有效期
userid	支付宝用户标识	String	是	支付宝用户标识

同步响应结果示例：

{
  "alipay_open_auth_token_app_response": {
    "code": "10000",
    "msg": "Success",
    "app_auth_token": "201712BB_D179ffeb8dd48f89f81952768ca1B34",
    "app_refresh_token": "201712BB_d42f729c267473cad3ab89b5ba63C34",
    "auth_app_id": "2017120501354688",
    "expires_in": 31536000,
    "re_expires_in": 32140800,
    "user_id": "2088302181262340"
  },
  "sign": "KvbI8Z/KgM/QSt76OyBuQLyUSCnSiwcaXLaBdnH9hYZgmx2rnW5aiGX11W6Yu0HdRt0ckscgr7Ymy5Ux5X4xA0UxxTmvNWUU0/lZ8wu+2jX+tFU1OMV/dEKgcBGqaTGPhYqEKndXAmpHgKc/LMD62ump2BmeM2V8R5zLe0fGz8E="
}

注意：

换取令牌和刷新令牌返回报文不一样，具体请参考上方两个示例。
开发者代替商户发起请求时请务必带上 app_auth_token，否则支付宝将认为是本应用替自己发起的请求。请注意 app_auth_token 是 POST 请求参数，不是 biz_content 的子参数；在 SDK 中带上 app_auth_token 代码示例。

request.putOtherTextParam("app_auth_token", "201611BB888ae9acd6e44fec9940d09201abfE16");

开发者代替商户发起请求时，POST 公共请求参数中的 app_id 应填写开发者的 app_id；如果业务参数 biz_content 中需要 AppId，则应填写商户的 AppId。

查询授权信息

接口名称：alipay.open.auth.token.app.query

当商户把服务窗、店铺等接口的权限授权给 ISV 之后，支付宝会给 ISV 颁发一个 app_auth_token。如若授权成功之后，ISV 想知道用户的授权信息，如授权者、授权接口列表等信息，可以调用本接口查询某个 app_auth_token 对应的授权信息。

请求参数说明

参数	参数名称	类型	必填	描述	范例
app_auth_token	商户授权令牌	String	是	通过该令牌来帮助商户发起请求，完成业务	201510BBaabdb44d8fd04607abf8d5931ec75D84

接口请求示例: 请先阅读 SDK 接入说明

AlipayClientalipayClient = newDefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID,APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY,"RSA2"); 
AlipayOpenAuthTokenAppQueryRequest request = newAlipayOpenAuthTokenAppQueryRequest(); 
request.setBizContent("{" +
"\"app_auth_token\":\"201509BBeff9351ad1874306903e96b91d248A36\""+ 
"  }"); 
AlipayOpenAuthTokenAppQueryResponse response =alipayClient.execute(request);
System.out.println(response.getBody());

同步响应参数说明

参数	参数名称	类型	必填	描述
user_id	授权商户的 ID	String	是	授权者的 PID
auth_app_id	授权商户的 AppId	String	是	授权商户的AppId（如果有服务窗，则为服务窗的AppId）
expires_in	令牌有效期	Number	是	交换令牌的有效期，单位秒，换算成天的话为365天
auth_methods	授权接口列表	String	是	当前 app_auth_token 的授权接口列表
auth_start	授权生效时间	Date	是	当前 app_auth_token 的授权生效时间
auth_end	授权失效时间	Date	是	当前 app_auth_token 的授权失效时间
status	状态	String	是	valid：有效状态；invalid：无效状态

同步响应结果示例

{
  "alipay_open_auth_token_app_query_response": {
    "auth_app_id": "2013121100055554",
    "auth_end": "2016-11-03 01:59:57",
    "auth_methods": [
      "\"alipay.open.auth.token.app.query\"",
      "\"alipay.system.oauth.token\"",
      "\"alipay.open.auth.token.app\""
    ],
    "auth_start": "2015-11-03 01:59:57",
    "code": "10000",
    "expires_in": 31536000,
    "msg": "Success",
    "status": "valid",
    "user_id": "2088102150527498"
  }
}

SDK 接入说明

下载服务端 SDK

为了帮助开发者调用开放接口，我们提供了开放平台服务端 SDK，包含JAVA、PHP、.NET、Python 和 NodeJS 等多个语言版本，封装了签名&验签、HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。

各语言版本服务端 SDK 详细使用说明，请参考《服务端 SDK 说明》。

接口调用配置

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

关键参数说明:

配置参数	示例值解释	获取方式/示例值
URL	支付宝网关（固定）	https://openapi.alipay.com/gateway.do
APP_ID	APPID 即创建应用后生成	获取详情见创建应用
APP_PRIVATE_KEY	开发者私钥，由开发者自己生成	获取详见配置密钥
FORMAT	参数返回格式，只支持json	json（固定）
CHARSET	编码集，支持GBK/UTF-8	开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY	支付宝公钥，由支付宝生成	获取详见上面配置密钥
SIGN_TYPE	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2

接口调用

接口调用示例大致分为3步：

拼装业务参数；
将参数发送给开放平台服务端；
获取开放平台服务端返回值，并进行具体业务处理。

解除授权

商家在完成第三方应用授权后，可以自行在应用管理中心取消授权。点击 开发管理，查看已授权的第三方，点击 停止授权，即可解除授权。

关于沙箱

接入沙箱

沙箱是开放平台提供给开发者用户调试接口的环境，具体操作步骤见沙箱接入指南。

第三方应用接入沙箱注意点

第三方应用授权支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
单个第三方应用授权的拼接示例为：https://openauth.alipaydev.com/oauth2/appToAppAuth.htm?app_id=APPID&redirect_uri=REDIRECT_URI （以上链接要在沙箱环境下使用）
批量第三方应用授权的拼接示例为：https://openauth.alipay.com/oauth2/appToAppBatchAuth.htm?app_id=2015101400446982&application_type=TINYAPP,WEBAPP&redirect_uri=http://www.baidu.com
授权时使用商户账号进行授权，不要使用买家账号授权。

API 列表

序号	接口英文名	接口中文名	API文档
1	alipay.open.auth.token.app	换取应用授权令牌接口	查看文档
2	alipay.open.auth.token.app.query	查询某个应用授权 AppAuthToken 的授权信息接口	查看文档

本接口及文档资料由开放平台提供。您使用本接口，需要遵守开放平台相关协议及开放平台要求。

客服电话

第三方平台

第三方应用授权更新时间：2020-01-09

概述

授权流程

快速接入

第一步：创建应用

第二步：配置密钥

第三步：应用授权 URL 拼装

拼接规则

单个授权URL拼接规则

批量授权URL拼接规则

参数说明

使用场景

单个授权场景举例

批量授权场景举例

第四步：获取 app_auth_code

第五步：使用 app_auth_code 换取 app_auth_token

获取商户信息

获取授权令牌

刷新授权令牌

查询授权信息

SDK 接入说明

解除授权

关于沙箱

API 列表

第三方平台

第三方应用授权 更新时间：2020-01-09

概述

授权流程

快速接入

第一步：创建应用

第二步：配置密钥

第三步：应用授权 URL 拼装

拼接规则

单个授权URL拼接规则

批量授权URL拼接规则

参数说明

使用场景

单个授权场景举例

批量授权场景举例

第四步：获取 app_auth_code

第五步：使用 app_auth_code 换取 app_auth_token

获取商户信息

获取授权令牌

刷新授权令牌

查询授权信息

SDK 接入说明

解除授权

关于沙箱

API 列表

第三方应用授权更新时间：2020-01-09