产品介绍

简介

所有支付宝开放平台的用户信息的读写均需要经过用户的许可才允许开发者使用,用户授权基于国际标准的 OAuth2.0 授权机制,基于此机制开发者可以获取支付宝用户信息、给用户发会员卡等。

术语解释:

scope:授权范围,一个 scope 表示开发者需要请求用户授权的权限范围,一个 scope 包含至少一个 OpenAPI 接口或者 JsAPI 接口,一次授权可以组合多个 scope 做组合授权。
auth_code:授权码,与JsAPI 获取到的 authCode 相同,临时的用户授权凭证。使用规则如下:
auth_code 单次有效,不可重复使用。
有效期为 3 分钟到 24 小时(开放平台规则会根据具体的业务场景动态调整 auth_code 的有效期,但是不会低于 3 分钟,同时也不会超过 24 小时),超过有效期的 auth_code 即使未使用也将自动失效。
用户的每次授权动作都会生成一个新的 auth_code。
基于安全考虑,开发者在获取 auth_code(用户授权码)后应尽快调用alipay.system.oauth.token(换取授权访问令牌) 接口换取 access_token(访问令牌)。

关联产品推荐

获取会员基础信息

准入条件

该能力对企业支付宝账户和个人支付宝账户(含个体工商户)均开放。
小程序开发者需充分尊重用户个人隐私,妥善使用用户授权。若发现信息存在超出约定范围使用或者不合理使用等情况,开放平台有权永久收回该小程序的接口权限。

计费模式

免费。
快速示例
如下示例仅演示接口调用流程,为了创造更良好的支付宝小程序用户体验,小程序不允许首屏弹窗引导用户授权。需要在用户充分了解小程序的业务内容后再引导用户授权,建议将小程序授权环节放在业务流程中。
获取用户授权的演示效果请参考以下示例,实际返回的授权码以真机调试为准。
接入指南

接入流程

以获取用户信息举例,整体的接入流程如下(若需要授权其它信息,只需要在调用 getAuthCode 的时候的 scopes 参数使用不同的 scope 即可)。

scopes 列表

scopes
说明
包含的 openapi 接口
auth_base
静默授权,不会发起授权浮窗;在支付宝客户端获取 auth_code,传入服务端端调用alipay.system.oauth.token接口获取支付宝会员标识(user_id)。
无
auth_user
主动授权,需要用户手动点击同意,用户同意后,用于网站支付宝登录和获取用户信息(现已升级为“获取会员基础信息”,且新功能包不再使用 alipay.user.info.share 接口)功能。
auth_zhima
用户芝麻信息。

第一步:客户端获取 authcode

通过调用my.getAuthCode获取用户授权,在success 回调中可以获取到 authCode。js 代码如下:
my.getAuthCode({ scopes: ['auth_user'], // 主动授权:auth_user,静默授权:auth_base或者其它scope。如需同时获取用户多项授权,可在 scopes 中传入多个 scope 值。 success: (res) => { if (res.authCode) { // 认证成功 // 调用自己的服务端接口,让服务端进行后端的授权认证,并且利用session,需要解决跨域问题 my.request({ url: 'https://isv.com/auth', // 该url是您自己的服务地址,实现的功能是服务端拿到authcode去开放平台进行token验证 data: { authcode: res.authCode, }, success: () => { // 授权成功并且服务器端登录成功 }, fail: () => { // 根据自己的业务场景来进行错误处理 }, }); } }, });

第二步:服务端获取 access_token、user_id

服务器端调用alipay.system.oauth.token(换取授权访问令牌) 接口换取授权访问令牌,开发者可通过获取到的 auth_code 换取 access_token(授权令牌) 和user_id (用户支付宝 ID)。
auth_code 作为换取 access_token 的票据,每次用户授权完成,回调地址中的 auth_code 将不一样,auth_code 只能使用一次,一天未被使用自动过期。

示例代码

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2"); AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest(); request.setGrantType("authorization_code"); request.setCode("4b203fe6c11548bcabd8da5bb087a83b"); AlipaySystemOauthTokenResponse response = alipayClient.execute(request); if(response.isSuccess()){ System.out.println("调用成功"); } else { System.out.println("调用失败"); }

重要入参说明

术语解释:refresh_token,刷新令牌,用于在授权令牌过期后刷新重新获取新的授权令牌,刷新令牌也有有效期。
grantType:授权类型,支持如下类型:
authorization_code:用户授权,此类型下 code 参数中传入用户授权码 auth_code 换取用户授权令牌 access_token,无需传入 refresh_token。
refresh_token:刷新令牌,此类型下传入有效的 refresh_token 用于刷新授权令牌,无需传入 code。
code:用户授权码,通过小程序接口获取到的 auth_code 参数。

响应示例

重要响应参数说明

user_id:用户支付宝 ID。
access_token:访问令牌。通过该令牌调用需要授权类接口。
expires_in:访问令牌的有效时间,单位是秒。
refresh_token:刷新令牌。通过该令牌可以刷新 access_token。
re_expires_in:刷新令牌的有效时间,单位是秒。
注意:
若接口同步响应有 alipay_user_id 请忽略,该字段已废除。用户支付宝 ID 为接口响应 user_id 值。
更多参数详情参见alipay.system.oauth.token(换取授权访问令牌) 接口文档。

调用服务端业务接口

在获取到 access_token 后,即可以继续使用该 token 调用 openapi 的授权类接口(比如alipay.user.info.share、alipay.marketing.card.open 等),请注意 token 的权限范围和时效性。
API 列表

接口英文名
接口中文名
my.getAuthCode
获取用户授权码
alipay.system.oauth.token
换取授权访问令牌

如果您在调用 API 时出现报错:
欢迎前往开放社区 提问、留言。
在公共错误码 中根据错误码的类型,查找相关错误码及解决方案。
在云排查 中排查遇到的问题。
您还可以在文档中心 直接搜索您要的答案。
常见问题

Q:小程序如何实现用户授权?

A:小程序不支持使用拼接授权链接进行授权,建议使用my.getAuthCode 实现用户授权、用户登录等。

Q:先调用 my.getAuthCode,再调用 my.getOpenUserInfo 会出现两次授权窗口,是否有方法可以实现只出现一个授权弹框?

A:正常获取会员基础信息是需要弹窗两次进行授权确认的,一次是 my.getAuthCode 获取用户授权码的授权框, 一次是 my.getOpenUserInfo 中获取用户基础信息的授权框。
my.getAuthCode 使用静默授权方法(令scopes 为auth_base)即可实现只出现一个授权弹框。示例代码如下:
my.getAuthCode({ scopes: ['auth_base'], success: (res) => { my.alert({ content: res.authCode, }); }, });

Q:如何打印 my.getAuthCode 获取到的 authCode?

A:在IDE 中使用 console.log,在console 里打印即可。示例代码如下:
my.getAuthCode({ scopes: 'auth_user', success: (res) => { console.log(res.authCode), my.alert({ content: res.authCode, }); }, });
效果如下图所示:

Q:为什么要使用用户授权my.getAuthCode API?

A:开发者在支付宝开放平台上读写用户信息,均需经过用户许可。支付宝开放平台的用户授权基于国际标准的 OAuth2.0 授权机制。基于此机制,使用 my.getAuthCode API 得到用户授权后,方可进行获取用户信息、给用户发放会员卡等操作。

Q:为什么不允许在小程序首屏即使用用户授权 API 弹窗获取用户授权?

A:为了创造更良好的支付宝小程序用户体验,在小程序的首屏引导用户授权是不被允许的。需要在用户充分了解小程序的业务内容后再引导用户授权,建议将小程序授权环节放在业务流程中。

Q:用户的 userID 可以通过用户授权 API 获取吗?

A:不可以,userID 需要在服务器端调用alipay.system.oauth.token 获取。

Q:为什么小程序获取会员基础信息根据 auth_code 获取 access_token 时提示 APPID 无效?

A:开发者获取 auth_code 关联的 APPID 需要与调用接口换取 token 时配置的小程序 APPID 相同。开发者可以点击https://open.alipay.com/platform/home.htm 进入支付宝开放平台查找自己的应用 APPID。

Q:为什么使用获取到的 access_token 时报错 aop.invalid-auth-token(无效的访问令牌 ) ?

A:参数设置的 auth_token 有误或已失效,alipay.system.oauth.token 接口获取的 access_token 有效时间,参考接口返回的 expires_in 参数显示的值。
附录:深入授权机制

用户授权 auth_code

说明:auth_code 一次有效,auth_code 有效期为 3 分钟到 24 小时(开放平台规则会根据具体的业务场景动态调整 auth_code 的有效期,但是不会低于 3 分钟,同时也不会超过 24 小时),超过有效期的 auth_code 即使未使用也将无法使用。 用户的每次授权动作都会生成一个新的 auth_code。
建议:基于安全考虑,开发者在获取 auth_code(用户授权码)后应尽快调用alipay.system.oauth.token(换取授权访问令牌) 接口换取 access_token(访问令牌)。

授权 scope

说明:scope 为公开的资源,其使用不需要签约,但是其包含的接口是否需要签约请看具体的功能包或者接口定义。 开发者可以在授权请求中包含一个或者多个用户授权范围,每个授权范围称为一个 scope,一个 scope 包含若干个开放平台接口,请求的多个 scope 通过英文逗号分隔。 授权的流程是通用的,在不同的业务场景需要授权的范围不同,需要根据具体产品接入文档中指定的 scope 替换本文中的 scope 参数。