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

      applyToken

      The applyToken API can be used in two ways: with the consult API to obtain an access token, or independently to get a new access token via the refresh token when an existing access token expires.

      Structure

      A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see: 


      Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

      • If the data type of a field is Integer and its value is 20, set it as "20". 
      • If the data type of a field is Boolean and its value is true, set it as "true". 

      Request parameters

      grantType StringRequired

      Indicates which parameter is to be used to obtain the access token. Valid values are:

      • AUTHORIZATION_CODE: Authorization Code, which is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.
      • REFRESH_TOKEN: Refresh Token, which is used by authClient to exchange a refresh token for an access token when the access token has expired. This allows clients to continue to have a valid access token without further interaction with the user. 
      customerBelongsTo StringRequired

      The e-wallet that the customer uses. Valid values are:

      • TRUEMONEY: TrueMoney wallet
      • ALIPAY_HK: Alipay HK wallet
      • TNG: Touch 'n Go wallet
      • ALIPAY_CN: Alipay CN wallet 
      • GCASH: Gcash wallet
      • DANA: Dana wallet
      • KAKAOPAY: KakaoPay wallet
      • BKASH: bKash wallet

      More information about this field:

      • Maximum length: 16 characters
      authCode StringOptional

      The authorization code, which is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.

      Note: This field is required when the value of grantType is AUTHORIZATION_CODE. By specifying the value of grantType as AUTHORIZATION_CODE, merchants can request an access token with authCode.

      More information about this field:

      • Maximum length: 32 characters
      refreshToken StringOptional

      The refresh token, which is used by the auth client to exchange for a new access token when the access token expires. By using the refresh token, new access tokens can be obtained without further interaction with the user.

      Note: This field is required when the value of grantType is REFRESH_TOKEN.

      More information about this field:

      • Maximum length: 128 characters

      Response parameters

      result ResultRequired

      The request result contains information such as status and error codes.

      resultCode StringRequired

      Result code

      More information about this field:

      • Maximum length: 64 characters
      resultStatus StringRequired

      Result status. Valid values are: 

      • S: Indicates that the result status is successful. 
      • F: Indicates that the result status failed. 
      • U: Indicates that the result status is unknown.
      resultMessage StringOptional

      Result message

      More information about this field:

      • Maximum length: 256 characters
      accessToken StringOptional

      An access token that can be used to access the user resource scope.

      More information about this field:

      • Maximum length: 128 characters
      accessTokenExpiryTime Datetime Optional

      Access token expiration time. After the token expires, authClient will not be able to use this token to deduct from the user's account.

      More information about this field:

      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      refreshToken StringOptional

      The refresh token that is used by the auth client to exchange for a new access token when the access token expires. By using the refresh token, new access tokens can be obtained without further interaction with the user. 

      More information about this field:

      • Maximum length: 128 characters
      refreshTokenExpiryTime DatetimeOptional

      Refresh token expiration time, after which the auth client cannot use this token to retrieve a new access token. 

      More information about this field:

      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

      More information 

      This section gives additional information about other parameters. See the following list for details:

      • grantType
        By specifying the value of grantType as REFRESH_TOKEN, the merchant can request an access token with the refresh token. The refresh token is obtained from the response of the previous accessToken applyToken call.
      • authCode:
        The parameter is required when the value of grantType is AUTHORIZATION_CODE. The value of authCode is obtained from the reconstructed URL returned by Alipay+ MPP. By specifying the value of grantType as AUTHORIZATION_CODE, merchants can request an access token with authCode.
      • accessToken:
        When authorization application is successful [result.resultStatus == S], the auth client might use accessToken to access the corresponding user's resource scope.
      • accessTokenExpiryTime:
        This parameter must be returned when authorization application is successful [result.resultStatus == S], and the accessToken will be invalid after accessTokenExpiryTime.
      • refreshToken:
        This parameter must be returned when authorization application is successful [result.resultStatus == S], and the merchant can use the refreshToken to request for a new accessToken.
      • refreshTokenExpiryTime:
        This parameter must be returned when authorization application is successful [result.resultStatus == S], and the merchant will not be able to use the refreshToken to retrieve a new accessToken after refreshTokenExpiryTime. 

      Responses for different wallets

      The responses for different wallets have slight differences in the extendInfo field.

      Result process logic

      For different request results, different actions are to be performed. See the following list for details:

      • If the value of result.resultStatus is S, then the application is successful. Merchant can use the access token to access the corresponding user resource scope.
      • If the value of result.resultStatus is F or U, retry the process. 

      Error codes

      Error codes are usually classified into the following categories:

      • Common error codes: common for all online and in-store payment APIs.
      • API-specific error codes: listed in the following table.  

      Result/Error codes

      CodeValueMessageFurther action
      SUCCESSSSuccess

      The authorization is completed, store accessToken and other related fields.

      INVALID_AUTHCODEFThe authorization code is invalid.

      Re-initiates the authorization, you need to call the consult interface to obtain the authcode.

      INVALID_REFRESH_TOKENFThe refresh token is invalid.

      Use a valid refreshToken to re-initiate the request.

      EXPIRED_REFRESH_TOKENFThe refresh token is expired.

      The refresh token is expired and re-sign is needed.

      CLIENT_INVALIDFThe client is invalid.

      Check whether the clientId is correct.

      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

      Check whether the HTTP method is correct.

      MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

      Check whether the media type is correct.

      Request/Response Code

      Request

      Method

      POST

      Endpoint

      /v1/authorizations/applyToken

      Header

      Accept: application/json

      URL

      Domain name

      Request Body
      Request parameters
      Get accessToken with authCode
      Get accessToken with refreshToken
      Response Body
      Body content