alipay.system.oauth.token (Obtain the access token)
The proxy call by third parties is supported
Use this API to obtain the access token.
Public parameters
Request URL
Environment | HTTPS request URL |
Production environment | https://openapi.alipay.com/gateway.do |
Public request parameters
Parameter | Type | Required | Max length | Description | Sample |
app_id | String | Y | 32 | The app ID that Alipay assigns to the developer. | 2014072300007148 |
method | String | Y | 128 | The API name. | alipay.system.oauth.token |
format | String | N | 40 | Only JSON is supported. | JSON |
charset | String | Y | 10 | Request encoding format. Such as utf-8, gbk, and gb2312. | utf-8 |
sign_type | String | Y | 10 | The signature algorithm used by the merchant to generate the sign string. Currently, RSA and RSA2 are supported. RSA2 is preferred. | RSA2 |
sign | String | Y | 256 | The sign string of the merchant’s request parameters. For details, see Signature | For details, see the example. |
timestamp | String | Y | 19 | The time when the request is sent. Format: "yyyy-MM-dd HH:mm:ss”. | 2014-07-24 03:07:50 |
version | String | Y | 3 | The API version. The value is fixed to be 1.0. | 1.0 |
app_auth_token | String | N | 40 | For details, see Overview of the app authorization. |
Request parameters
Parameter | Type | Required | Max length | Description |
grant_type | String | Y | - | When the value is authorization_code, use the authorization code to obtain the access token; when the value is refresh_token, use the refresh_token to refresh the access token. |
code | String | N | - | Authorization code that can be obtained after users make an authorization. |
refresh_token | String | N | - | Refresh token is used to refresh the access token, and a new refresh token is returned together with the new access token. See the refresh_token field in response parameters for details. |
Response parameters
Parameter | Type | Required | Max length | Description | Sample |
user_id | String | Y | 16 | Users’ unique Alipay user ID | 2088102150477652 |
access_token | String | Y | 40 | Access token that can be used to call the APIs that needs authorization. | 20120823ac6ffaa4d2d84e7384bf983531473993 |
expires_in | String | Y | 16 | The validity time of the token. Unit: second. | 3600 |
refresh_token | String | Y | 40 | The refresh tocken. By this token you can refresh the access_token token. | 20120823ac6ffdsdf2d84e7384bf983531473993 |
re_expires_in | String | Y | 16 | The validity time of the refresh token. Unit is second. | 3600 |
Request samples
- JAVA
copy
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");
request.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("Call succeeds");
} else {
System.out.println("Call fails");
}
- .NET
copy
IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false);
AlipaySystemOauthTokenRequest request= new AlipaySystemOauthTokenRequest() ;
request.GrantType = "authorization_code";
request.Code = "4b203fe6c11548bcabd8da5bb087a83b";
request.RefreshToken = "201208134b203fe6c11548bcabd8da5bb087a83b";
AlipaySystemOauthTokenResponse response=client.execute(request);
Console.WriteLine(response.Body);
- PHP
copy
$aop = new AopClient ();
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
$aop->appId = 'your app_id';
$aop->rsaPrivateKey = 'Please fill in the developer's private key in a line of string, moving the head, tail, and carriage return';
$aop->alipayrsaPublicKey='Please fill in Alipay public key in a line of string';
$aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='GBK';
$aop->format='json';
$request = new AlipaySystemOauthTokenRequest ();
$request->setGrantType("authorization_code");
$request->setCode("4b203fe6c11548bcabd8da5bb087a83b");
$request->setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
$result = $aop->execute ( $request);
- HTTP request source code
copy
https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=alipay.system.oauth.token&app_id=4472&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&grant_type=
"authorization_code"
&code=
"4b203fe6c11548bcabd8da5bb087a83b"
&refresh_token=
"201208134b203fe6c11548bcabd8da5bb087a83b"
//To ensure a secure communication, verify whether the sign value in the response sample is provided by Ant finance.
Response samples
- JSON sample
copy
{
"alipay_system_oauth_token_response": {
"user_id": "2088102150477652",
"access_token": "20120823ac6ffaa4d2d84e7384bf983531473993",
"expires_in": "3600",
"refresh_token": "20120823ac6ffdsdf2d84e7384bf983531473993",
"re_expires_in": "3600"
}
}
- XML sample
copy
<alipay_system_oauth_token_response>
<code>10000</code>
<msg>Success</msg> <alipay_user_id>Obsolete. Do not use it.</alipay_user_id>
<user_id>2088102150477652</user_id>
<access_token>20120823ac6ffaa4d2d84e7384bf983531473993</access_token>
<expires_in>3600</expires_in>
<refresh_token>20120823ac6ffdsdf2d84e7384bf983531473993</refresh_token>
<re_expires_in>3600</re_expires_in>
<auth_token_type>permanent</auth_token_type>
</alipay_system_oauth_token_response>
Exceptional sample
copy
{
"alipay_system_oauth_token_response": {
"code": "20000",
"msg": "Service Currently Unavailable",
"sub_code": "isp.unknow-error",
"sub_msg": "System busy"
},
"sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
Business error codes
Error code | Description | Solution |
isv.grant-type-invalid | The value of grant_type is incorrect. | The value must be either authorization_code or refresh_toke. If authorization_code is passed in, then use the authorization code to obtain the access token; if refresh_token is passed in, then refresh the access token. |
isv.code-invalid | The authorization code (auth_code) is incorrect or expired. | Use a valid auth_code to obtain the access token, or guide the user to re-authorize. |
isv.refresh-token-invalid | Refresh token is incorrect or the status is incorrect. | Use a valid refresh_token to refresh the access token, or guide the user to re-authorize. |
isv.refresh-token-time-out | Refresh token is expired. | Use a valid refresh_token to refresh the access token, or guide the user to re-authorize. |
isv.refreshed-token-invalid | After refreshing, the access token returned is invalid. | Use the returned refresh token to refresh again. |
isv.invalid-app-id | The app ID is inconsistent with the application which is authorized by the token. | Pass in the correct app_id and token. If more than one app_ids exist under the developer’s Alipay account, or the developer manages several app_ids that under different Alipay accounts, don’t mix the auth codes of different app_ids. |
isp.unknow-error | Unknown error | Try again, or contact Alipay customer service. |