授权流程

在生活号或者 H5 应用内，授权流程如下图所示：

通过调用 JSAPI ap.getAuthCode 接口在当前页面唤起半屏授权浮层；

用户确认授权后，接口返回 auth_code；

开发者通过 alipay.system.oauth.token（换取授权访问令牌接口），使用 auth_code 换取 access_token 及用户的 user_id。
如果需要除 user_id 以外的其他信息，则使用 access_token 调用 alipay.user.info.share（支付宝会员授权信息查询接口）获得用户信息。

操作步骤

第一步：唤起半屏授权框

通过调用 JSAPI ap.getAuthCode 接口在当前页面唤起半屏授权浮层。

**注意：**JSAPI 须在授权回调地址页面中调用，否则会导致无法正常使用。

前端显示效果

代码示例

<script src = "https://gw.alipayobjects.com/as/g/h5-lib/alipayjsapi/3.1.1/alipayjsapi.min.js"> </script> 
<button id = "test"> getAuthCode </button>
<script>
 document.querySelector('#test').addEventListener('click',function(){
    ap.getAuthCode ({
      appId :  '${appId}' ,
      scopes : ['auth_user'],
   },function(res){
      ap.alert (JSON.stringify(res));
   });
});
</script>

入参说明

参数	类型	必填	描述
scopes	Array	否	授权类型，默认 auth_base。支持以下两种类型：auth_base(静默授权)：静默授权，用户无需点击确认授权，默认返回 auth_code，该授权码不支持获取用户信息。 auth_user(主动授权)：首次授权需要用户手动点击同意，用户同意后，返回 auth_code；商家需要考虑用户拒绝授权的情况并进行相应容错。如果授权关系依旧存在，下次进入页面时也会静默授权。
appId	String	是	开放平台应用 id，详情请参见查看 APPID。
showErrorTip	boolean	否	是否显示出错弹框。建议传入 false 自行处理异常，默认 true。

注意：服务商代商家获取会员信息时，用户信息实际还是授权给授权商家的，因此 URL 拼接链接需注意 appId 和 JSAPI ap.getAuthCode 接口设置页面：

appId：授权商家 APPID（即第三方应用授权返回 app_auth_token 对应的 auth_app_id ）。

JSAPI ap.getAuthCode 需要在授权商家应用配置的授权回调页面中调用，否则会导致无法正常使用。

callback 参数说明

参数	类型	描述
authCode	String	授权码，用于在之后通过 alipay.system.oauth.token（换取授权访问令牌接口）换取 access_token 和 user_id。
error	Number	错误码。详情请参见错误码说明。
errorMessage	String	错误信息。
errorDesc	String	错误描述（中文）。

错误码说明

错误码	说明
2	参数错误。
10	获取授权过程中的其他错误。
11	用户取消授权。
12	rpc 网络错误。
15	授权回调地址不合法，请保证已配置 https 开头的授权回调地址，且当前页面地址需要和配置的一致。

第二步：换取 access_token 和 user_id

得到 auth_code 后，开发者通过 alipay.system.oauth.token（换取授权访问令牌接口），使用 auth_code 换取 access_token 及用户的 user_id。auth_code 作为换取 access_token 的凭证，每次用户授权完成后，返回参数中的 auth_code 将不一样，auth_code 只能使用一次，24 小时内未被使用自动过期。

注意：alipay.system.oauth.token（换取授权访问令牌接口）的返回值 alipay_user_id 已废弃，请勿使用，需要获取的 userId 值为返回值中的 user_id 。

接口请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipaySystemOauthApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipaySystemOauthApiToken {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipaySystemOauthApi api = new AlipaySystemOauthApi();
        AlipaySystemOauthTokenModel data = new AlipaySystemOauthTokenModel();
        data.setCode("4b203fe6c11548bcabd8da5bb087a83b");
        data.setGrantType("authorization_code");
        data.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
        try {
            AlipaySystemOauthTokenResponseModel response = api.token(data);
        } catch (ApiException e) {
            AlipaySystemOauthTokenDefaultResponse errorObject = (AlipaySystemOauthTokenDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

请求参数说明

参数	类型	必填	描述
grant_type	String	是	授权类型。值为 authorization_code 时，代表用 code 换取；值为 refresh_token 时，代表用 refresh_token 换取。示例值：authorization_code
code	String	与 refresh_token 二选一	授权码。用户对应用授权后得到，即第二步中开发者获取到的 auth_code 值。示例值：4b203fe6c11548bcabd8da5bb087a83b
refresh_token	String	与 code 二选一	刷新令牌。刷新 access_token 时使用。示例值：201208134b203fe6c11548bcabd8da5bb087a83b

同步响应结果示例

{
    "access_token":"20120823ac6ffaa4d2d84e7384bf983531473993",
    "refresh_token":"20120823ac6ffdsdf2d84e7384bf983531473993",
    "user_id":"2088102150477652",
    "re_expires_in":"3600",
    "auth_start":"2010-11-11 11:11:11",
    "expires_in":"3600"
}

同步响应参数说明

参数	类型	必填	最大长度	描述
access_token	String	是	40	交换令牌。用于获取用户信息。示例值：publicpBa869cad0990e4e17a57ecf7c5469a4b2
user_id	String	是	16	用户的 userID。支付宝用户的唯一 userId。示例值：2088102104711111
expires_in	String	是	16	令牌有效期。交换令牌的有效期，单位秒。示例值：300
re_expires_in	String	是	16	刷新令牌有效期，单位秒。示例值：300
refresh_token	String	是	40	刷新令牌。通过该令牌可以刷新 access_token。示例值：publicpB0ff17e364f0743c79b0b0d7f55e20bfc

第三步：获取用户信息

开发者在获取了用户的 user_id 后，如果想获取头像、昵称、省份等其他信息，需要调用 alipay.user.info.share（支付宝会员授权信息查询接口）。

接口请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipaySystemOauthApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipaySystemOauthApiToken {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipaySystemOauthApi api = new AlipaySystemOauthApi();
        AlipaySystemOauthTokenModel data = new AlipaySystemOauthTokenModel();
        data.setCode("4b203fe6c11548bcabd8da5bb087a83b");
        data.setGrantType("authorization_code");
        data.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
        try {
            AlipaySystemOauthTokenResponseModel response = api.token(data);
        } catch (ApiException e) {
            AlipaySystemOauthTokenDefaultResponse errorObject = (AlipaySystemOauthTokenDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

公共请求参数说明

参数	类型	必填	描述
auth_token	String	是	授权令牌。通过 auth_code 获取的 access_token。示例值：publicpB9ea460ff5b5c468c9ccf5e967dc34963

同步响应结果示例

{
    "province":"安徽省",
    "gender":"F",
    "user_id":"2088102104794936",
    "city":"安庆",
    "nick_name":"支付宝小二",
    "avatar":"http://tfsimg.alipay.com/images/partner/T1uIxXXbpXXXXXXXX"
}

同步响应参数说明

参数	类型	描述
user_id	String	支付宝用户的会员 ID，2088 开头的 16 位数字。示例值：2088102104711111
avatar	String	用户头像。如果没有数据的时候不会返回该数据，请做好容错。示例值：https://tfsimg.alipay.com/images/partner/T1k0xiXXRnXXXXXXXX
nick_name	String	用户昵称。如果没有数据的时候不会返回该数据，请做好容错。示例值：张三

结果码说明

同步返回结果码	描述
10000	业务处理成功。
40001～40006	业务处理失败。具体失败原因请参考公共错误码。其它请参考 API 文档。
20000	业务出现未知错误或者系统异常。业务出现未知错误或者系统异常（请一定在确定本次调用结果后，发起重试），可调用查询接口发起查询确定结果。

消息通知

商家/服务商创建、修改及用户领取商家券等场景，支付宝都将通过 From 蚂蚁消息通知向商家应用或第三方应用应用网关推送异步通知消息，同步对应操作结果。

若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。

第一步：订阅消息

当用户取消用户信息授权时，支付宝将通过 alipay.open.auth.userauth.cancelled（用户授权取消消息接口），发送此消息给被授权方。商家/服务商需根据订阅消息指引，为接入的应用订阅如下消息接口。

**注意：**仅完成订阅后才会收到支付宝发送的对应异步通知消息。

第二步：验签

商家/服务商可使用支付宝 SDK 可根据使用生成密钥验签指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。

第三步：反馈消息接收结果

收到异步通知完成验签后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其他值，表示消息获取失败，支付宝会根据投递重试策略重新发送消息到应用网关地址。

**说明：**完成异步通知验签时，如果验签成功返回 success，验签失败返回 fail，重新接收异步进行处理。

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

用户授权取消消息通知

用户取消用户信息授权时，支付宝将通过 alipay.open.auth.userauth.cancelled（用户授权取消消息接口），发送此消息给被授权方。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"app_id":"2014072300007148","user_id":"2088102104711111","cancel_time":"1514210452731"
}
&msg_method=alipay.open.auth.userauth.cancelled&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

生活号/H5 内获取用户信息

授权流程#

操作步骤#

第一步：唤起半屏授权框#

前端显示效果#

代码示例#

入参说明#

callback 参数说明#

错误码说明#

第二步：换取 access_token 和 user_id#

接口请求示例#

请求参数说明#

同步响应结果示例#

同步响应参数说明#

第三步：获取用户信息#

接口请求示例#

公共请求参数说明#

同步响应结果示例#

同步响应参数说明#

结果码说明#

消息通知#

第一步：订阅消息#

第二步：验签#

第三步：反馈消息接收结果#

用户授权取消消息通知#

消息示例#

授权流程

操作步骤

第一步：唤起半屏授权框

前端显示效果

代码示例

入参说明

callback 参数说明

错误码说明

第二步：换取 access_token 和 user_id

接口请求示例

请求参数说明

同步响应结果示例

同步响应参数说明

第三步：获取用户信息

接口请求示例

公共请求参数说明

同步响应结果示例

同步响应参数说明

结果码说明

消息通知

第一步：订阅消息

第二步：验签

第三步：反馈消息接收结果

用户授权取消消息通知

消息示例