开放平台
获取会员信息快速接入
该文档主要面向需要入驻蚂蚁金服开放平台的产品、架构、开发等相关人员， 需要有基本的程序开发背景。通过该文档能够快速集成（获取会员信息）功能，接入前需要入驻开放平台并创建了应用，应用已申请该接口权限并配置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、昵称、性别、省份、城市、用户头像、用户类型、用户状态、是否实名认证、是否是学生等信息。
授权流程
如上图所示，对于开发者而言，需要完成以下工作：
- 按照规则拼接授权页面的链接，并且引导用户跳转至该链接；
- 用户在授权页面上确认授权后，将跳转到开发者指定的回调页，并且带上auth_code；
- 开发者通过auth_code换取access_token及用户的userId；
- 如果需要除userId以外的其他信息，则使用access_token调用用户信息共享接口获取。
以下将对整个流程做详细介绍：
第一步：URL拼接与scope详解
url拼接规则：https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL
使用场景举例：开发者通过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代表个人账户 | 可空 | 1 |
| user_status |
用户状态 | String | Q代表快速注册用户 T代表已认证用户 B代表被冻结账户 W代表已注册，未激活的账户 | 可空 | T |
| is_certified |
是否通过实名认证 | String | T是通过 F是没有实名认证 | 可空 | T |
| is_student_certified |
是否是学生 | String | T是学生 F不是学生 | 可空 | T |
接口调用结果码说明
| 同步返回结果码 | 含义 | 说明 |
|---|---|---|
| 10000 |
业务处理成功 | |
| 40001～40006 | 业务处理失败 | 具体失败原因请参考公共错误码。其它请参考API文档。 |
| 20000 | 业务出现未知错误或者系统异常 | 业务出现未知错误或者系统异常(请一定在确定本次调用结果后，发起重试)，可调用查询接口发起查询确定结果。 |
关于沙箱
如何接入沙箱
获取用户信息沙箱接入注意点
