获取会员信息快速接入

该文档主要面向需要入驻蚂蚁金服开放平台的产品、架构、开发等相关人员, 需要有基本的程序开发背景。通过该文档能够快速集成(获取会员信息)功能,接入前需要入驻开放平台并创建了应用,应用已申请该接口权限并配置RSA密钥。

第一步:创建应用

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

使用场景举例:开发者可以使用该方案获取用户的userId、头像、昵称等基础信息。想要调用该接口,需要先在开放平台管理中心的应用详情中开通获取用户信息的功能,如下图所示:

第二步:配置密钥

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

第三步:搭建和配置开发环境

1. 下载服务端SDK

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

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

2. 接口调用配置

在SDK调用前需要进行初始化,以Java代码为示例如下:

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

关键参数说明:

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

第四步:调用接口获取用户信息

注意:
申请获取用户信息功能时默认可获取的用户信息包含用户ID、昵称、性别、省份、城市、用户头像、用户类型、用户状态、是否实名认证、是否是学生等信息。

授权流程

如上图所示,对于开发者而言,需要完成以下工作:

  1. 按照规则拼接授权页面的链接,并且引导用户跳转至该链接;
  2. 用户在授权页面上确认授权后,将跳转到开发者指定的回调页,并且带上auth_code;
  3. 开发者通过auth_code换取access_token及用户的userId;
  4. 如果需要除userId以外的其他信息,则使用access_token调用用户信息共享接口获取。

以下将对整个流程做详细介绍:

第一步:URL拼接与scope详解

url拼接规则:https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL

TIPS:沙箱拼接规则详见关于沙箱

使用场景举例:开发者通过URL拼接方案,构造授权页面,并且引导用户授权。

url参数说明

参数名 是否必须 描述
app_id 开发者应用的app_id
scope 接口权限值,目前只支持auth_user和auth_base两个值
redirect_uri 回调页面,是 经过转义 的url链接(url必须以http或者https开头),比如:http%3A%2F%2Fexample.com
在请求之前,开发者需要先到开发者中心对应应用内,配置授权回调地址。
state 商户自定义参数,用户授权后,重定向到redirect_uri时会原样回传给商户。 为防止CSRF攻击,建议开发者请求授权时传入state参数,该参数要做到既不可预测,又可以证明客户端和当前第三方网站的登录认证状态存在关联。

关于redirect_uri的说明:
接口会校验授权链接中配置的redirect_uri与应用中配置的授权链接是否一致。详细说明: 如果开发者在应用中配置的授权链接是:https://auth.example.com/authCallBack,则redirect_uri内容为https://auth.example.com/authCallBack的encode形式https%3A%2F%2Fauth.example.com%2FauthCallBack。授权回调地址对应的域名(auth.example.com)下的页面http://auth.example.com/authCallBack、https://auth.example.com/authRedirect、https://auth.example.com/都可以进行OAuth2.0授权。但与(auth.example.com)关联的二三级域名,如:http://www.example.com/、http://example.com/无法进行OAuth2.0授权。

关于scope的说明:

  • auth_base:以auth_base为scope发起的网页授权,是用来获取进入页面的用户的userId的,并且是静默授权并自动跳转到回调页的。用户感知的就是直接进入了回调页(通常是业务页面)。
  • auth_user:以auth_user为scope发起的网页授权,是用来获取用户的基本信息的(比如头像、昵称等)。但这种授权需要用户手动同意,用户同意后,就可在授权后获取到该用户的基本信息。若想获取用户信息,scope的值中需要有该值存在,如scope=auth_user,auth_base。

PC授权页面示例:

H5授权页面示例:

注:H5授权页只能在支付宝客户端里使用,否则会报错,如下。

第二步:获取auth_code

当用户授权成功后,会跳转至开发者定义的回调页面,支付宝会在回调页面请求中加入参数,包括auth_code、app_id、scope等,需要注意的是支付宝仅保证auth_code、app_id以及scope参数的有效性。支付宝请求开发者回调页面示例如下:

http://example.com/doc/toAuthPage.html?app_id=2014101500013658&source=alipay_wallet&scope=auth_user&auth_code=ca34ea491e7146cc87d25fca24c4cD11

第三步:使用auth_code换取接口access_token及用户userId

接口名称:alipay.system.oauth.token

换取授权访问令牌,开发者可通过获取到的auth_code换取access_token和用户userId。auth_code作为换取access_token的票据,每次用户授权完成,回调地址中的auth_code将不一样,auth_code只能使用一次,一天未被使用自动过期。

接口请求示例

REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
    app_id=2014070100171525
    method=alipay.system.oauth.token
    charset=GBK
    sign_type=RSA2
    timestamp=2014-01-01 08:08:08
    sign=rXaTEfJ7WTDsP1DWRPHARW3uOr19+fzlngMCJBvbhP1XPEa9qZwGGng9oMDloABpJMT2SGeOj46+BUkqCGRO9fH90Vci3hOH01BfYnbhJz3ADK2h7gpjlponx4/sxELN6f2GXi51XKiHKnxMA9XpLLo68q+roY0M/ZFQ1UdnqeM=
    version=1.0
    grant_type=authorization_code
    code=4b203fe6c11548bcabd8da5bb087a83b
    refresh_token=201208134b203fe6c11548bcabd8da5bb087a83b

接口调用示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
request.setCode("2e4248c2f50b4653bf18ecee3466UC18");
request.setGrantType("authorization_code");
try {
    AlipaySystemOauthTokenResponse oauthTokenResponse = alipayClient.execute(request);
    System.out.println(oauthTokenResponse.getAccessToken());
} catch (AlipayApiException e) {
    //处理异常
    e.printStackTrace();
}

请求参数说明

参数 参数名称 类型(长度范围) 参数说明 是否可为空 样例
grant_type 授权类型 String 值为authorization_code时,代表用code换取;值为refresh_token时,代表用refresh_token换取 不可空 authorization_code
code 授权码 String 用户对应用授权后得到,即第二步中开发者获取到的auth_code值 与refresh_token二选一 4b203fe6c11548bcabd8da5bb087a83b
refresh_token 刷新令牌 String 刷新access_token时使用 与code二选一 201208134b203fe6c11548bcabd8da5bb087a83b

同步响应结果示例

{
    "alipay_system_oauth_token_response": {
        "access_token": "publicpBa869cad0990e4e17a57ecf7c5469a4b2",
        "user_id": "2088411964574197",
        "expires_in": 300,
        "re_expires_in": 300,
        "refresh_token": "publicpB0ff17e364f0743c79b0b0d7f55e20bfc"
    },
    "sign": "xDffQVBBelDiY/FdJi4/a2iQV1I7TgKDFf/9BUCe6+l1UB55YDOdlCAir8CGlTfa0zLYdX0UaYAa43zY2jLhCTDG+d6EjhCBWsNY74yTdiM95kTNsREgAt4PkOkpsbyZVXdLIShxLFAqI49GIv82J3YtzBcVDDdDeqFcUhfasII="
}

同步响应参数说明

参数 参数名称 类型(长度范围) 参数说明 是否可为空 样例

access_token

交换令牌

String

用于获取用户信息

不可空

publicpBa869cad0990e4e17a57ecf7c5469a4b2

user_id

用户的userId

String

支付宝用户的唯一userId

不可空

2088411964574197

expires_in

令牌有效期

Number

交换令牌的有效期,单位秒

不可空

300

re_expires_in

刷新令牌有效期

Number

刷新令牌有效期,单位秒

不可空

300

refresh_token

刷新令牌

String

通过该令牌可以刷新access_token

不可空

publicpB0ff17e364f0743c79b0b0d7f55e20bfc

第四步:调用接口获取用户信息

如果scope=auth_base,在第三步就可以获取到用户的userId,无需走第四步。如果scope=auth_user,才需要走第四步,通过access_token调用用户信息共享接口获取用户信息。

接口名称:alipay.user.info.share

接口请求示例

REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
    app_id=2014070100171525
    method=alipay.user.info.share
    charset=GBK
    sign_type=RSA2
    timestamp=2014-01-01 08:08:08
    sign=rXaTEfJ7WTDsP1DWRPHARW3uOr19+fzlngMCJBvbhP1XPEa9qZwGGng9oMDloABpJMT2SGeOj46+BUkqCGRO9fH90Vci3hOH01BfYnbhJz3ADK2h7gpjlponx4/sxELN6f2GXi51XKiHKnxMA9XpLLo68q+roY0M/ZFQ1UdnqeM=
    version=1.0
    grant_type=authorization_code
    code=4b203fe6c11548bcabd8da5bb087a83b
    auth_token=201208134b203fe6c11548bcabd8da5bb087a83b

接口调用示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
AlipayUserInfoShareRequest request = new AlipayUserInfoShareRequest();
String auth_token = "composeBcd261a4867d94837a701f92816f18X18";
try {
    AlipayUserInfoShareResponse userinfoShareResponse = alipayClient.execute(request, auth_token);
    System.out.println(userinfoShareResponse.getBody());
} catch (AlipayApiException e) {
    //处理异常
    e.printStackTrace();
}

公共请求参数说明

参数 参数名称 类型(长度范围) 参数说明 是否可为空 样例

auth_token

授权令牌

String

通过auth_code获取的access_token

不可空

publicpB9ea460ff5b5c468c9ccf5e967dc34963

同步响应结果示例

{
    "alipay_user_info_share_response": {
        "code": "10000",
        "msg": "Success",
        "user_id": "2088102104794936",
        "avatar": "http://tfsimg.alipay.com/images/partner/T1uIxXXbpXXXXXXXX",
        "user_type": "1",
        "user_status": "T",
        "is_certified": "T",
        "province": "安徽省",
        "city": "安庆",
        "nick_name": "支付宝小二",
        "is_student_certified": "T",
        "gender": "F"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

同步响应参数说明

参数 参数名称 类型(长度范围) 参数说明 是否可为空 样例

user_id

支付宝用户id String 支付宝用户的Use_id 必填 2088102104794936

avatar

用户头像 String 如果没有数据的时候不会返回该数据,请做好容错 必填 https://tfsimg.alipay.com/images/partner/T1k0xiXXRnXXXXXXXX

nick_name

用户昵称 String 如果没有数据的时候不会返回该数据,请做好容错 必填 张三

province

省份 String 用户注册时填写的省份 如果没有数据的时候不会返回该数据,请做好容错 必填 浙江省

city

城市 String 用户注册时填写的城市, 如果没有数据的时候不会返回该数据,请做好容错 必填 杭州

gender

用户性别 String M为男性,F为女性, 如果没有数据的时候不会返回该数据,请做好容错 可空 M

user_type

用户类型  String 1代表公司账户2代表个人账户  可空 

 user_status

用户状态 String  Q代表快速注册用户 T代表已认证用户 B代表被冻结账户 W代表已注册,未激活的账户  可空 

is_certified 

是否通过实名认证 String  T是通过 F是没有实名认证  可空 

 is_student_certified

是否是学生 String  T是学生 F不是学生  可空 

接口调用结果码说明

同步返回结果码 含义 说明

10000

业务处理成功  
40001~40006 业务处理失败 具体失败原因请参考公共错误码。其它请参考API文档。
20000 业务出现未知错误或者系统异常 业务出现未知错误或者系统异常(请一定在确定本次调用结果后,发起重试),可调用查询接口发起查询确定结果。 

关于沙箱

如何接入沙箱

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

获取用户信息沙箱接入注意点

      1、获取用户信息支持沙箱接入;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;
      2、沙箱授权url链接拼接规则为:https://openauth.alipaydev.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL
onlineServer