第三方应用授权
概述
通过第三方应用授权,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拼接规则
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 的授权信息接口 |
本接口及文档资料由开放平台提供。您使用本接口,需要遵守开放平台相关协议及开放平台要求。