Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

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

EnvironmentHTTPS request URL
Production environmenthttps://openapi.alipay.com/gateway.do

Public request parameters

ParameterTypeRequiredMax lengthDescriptionSample
app_idStringY32The app ID that Alipay assigns to the developer.2014072300007148
methodStringY128The API name.alipay.system.oauth.token
formatStringN40Only JSON is supported.JSON
charsetStringY10Request encoding format. Such as utf-8, gbk, and gb2312.utf-8
sign_typeStringY10The signature algorithm used by the merchant to generate the sign string. Currently, RSA and RSA2 are supported. RSA2 is preferred.RSA2
signStringY256The sign string of the merchant’s request parameters. For details, see SignatureFor details, see the example.
timestampStringY19The time when the request is sent. Format: "yyyy-MM-dd HH:mm:ss”.2014-07-24 03:07:50
versionStringY3The API version. The value is fixed to be 1.0.1.0
app_auth_tokenStringN40For details, see Overview of the app authorization.

Request parameters

ParameterTypeRequiredMax lengthDescription
grant_typeStringY-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.
codeStringN-Authorization code that can be obtained after users make an authorization.
refresh_tokenStringN-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

ParameterTypeRequiredMax lengthDescriptionSample
user_idStringY16Users’ unique Alipay user ID2088102150477652
access_tokenStringY40Access token that can be used to call the APIs that needs authorization.20120823ac6ffaa4d2d84e7384bf983531473993
expires_inStringY16The validity time of the token. Unit: second.3600
refresh_tokenStringY40The refresh tocken. By this token you can refresh the access_token token.20120823ac6ffdsdf2d84e7384bf983531473993
re_expires_inStringY16The 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

Public error code

Error codeDescriptionSolution
isv.grant-type-invalidThe 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-invalidThe 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-invalidRefresh 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-outRefresh token is expired.Use a valid refresh_token to refresh the access token, or guide the user to re-authorize.
isv.refreshed-token-invalidAfter refreshing, the access token returned is invalid.Use the returned refresh token to refresh again.
isv.invalid-app-idThe 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-errorUnknown errorTry again, or contact Alipay customer service.