/v2/authorizations/applyToken

POST /v2/authorizations/applyToken

The applyToken API is used to obtain the access token.

This interface can be used in the following cases:

  • After the merchant receives authCode from Mini-Program, the merchant uses this interface to request the access token from e-wallet. In this scenario, the interface generally needs to be used with the Authorization Prepare Interface.
  • When the original token expires, the merchant requests a new access token by using the refresh token. In this scenario, this interface can be used independently.

Message structure

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

Request

Property

Data type

Required

Description

Example

authClientId 

String 

No

The unique identifier, which is allocated for the client.

Max. length: 128 characters.

"202016726873874774774xxxx"

grantType

String 

Yes

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

  • AUTHORIZATION_CODE: the authCode is to be used to retrieve the accessToken
  • REFRESH_TOKEN: the refreshToken is to be used to retrieve the accessToken

Max. length: 64 characters.

"AUTHORIZATION_CODE"

customerBelongsTo

String 

NO

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

  • TRUEMONEY
  • ALIPAY_HK
  • TNG
  • ALIPAY_CN
  • GCASH
  • DANA
  • KAKAOPAY
  • BKASH

If you call the interface through AC, you must pass this parameter.

"TNG"

authCode

String

No

It is required when grantType is AUTHORIZATION_CODE.

The authorization code 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 mini program's API, the mini program will get the authorization code from the response and use it to request an access token.

Max. length: 32 characters.

"2810111301lGZcM9CjlF91WH00039190xxxx"

refreshToken

String 

No

refreshToken is required when 

grantType is REFRESH_TOKEN.

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.

Max. length: 128 characters.

"2810111301lGZcM9CjlF91WH00039190xxxx"

extendInfo

String

No

The extended information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Response

Property

Data type

Required

Description

Example

result

Result

Yes

The request result, which contains information related to the request result, such as status and error codes.

{

   "resultCode": "SUCCESS",

   "resultStatus": "S",

   "resultMessage": "success"  

 }

accessToken

String 

No

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

When authorization application is successful [result.resultStatus == S], the auth client might use accessToken to acccess the corresponding user's resource scope.

Max. length: 128 characters.

"281010033AB2F588D14B43238637264FCA5AAF35xxxx"

accessTokenExpiryTime

String/Datetime

No

Access token expiration time, which follows the ISO 8601 standard. After this time, authClient cannot use this token to deduct from the user's account.

This parameter must be returned when the authorization application is successful [result.resultStatus == S],  and the accessToken will be invalid after accessTokenExpiryTime.

"2019-06-06T12:12:12+08:00"

refreshToken

String 

No

The refresh token 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.

This parameter must be returned when the authorization application is successful [result.resultStatus == S], and the merchant can use the refreshToken to request a new accessToken.

Max. length: 128 characters.

"2810100334F62CBC577F468AAC87CFC6C9107811xxxx"

refreshTokenExpiryTime

String/Datetime

No

Refresh token expiration time, after which the auth client cannot use this token to retrieve a new access token. The value follows the ISO 8601 standard.

This parameter must be returned when the 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.

"2019-06-08T12:12:12+08:00"

customerId

String 

No

Resource owner ID, maybe user ID, app ID of merchant's application, merchant ID.

Max. length: 64 characters.

"1000001119398804xxxx"

extendInfo

String

No

The extended information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows:

resultStatus

Description 

S

The authorization token application request is successful. The merchant can use the access token to access the corresponding user resource scope.

The corresponding result.resultCode is "SUCCESS" and the  result.resultMessage  is "Success".

U

The API status is unknown.  AuthClient may guide the user to try again.

The corresponding result.resultCode is "UNKNOWN_EXCEPTION" and result.resultMessage  is "An API calling is failed, which is caused by unknown reasons.".

For details, see the Common error codes section.

F

The request fails to send. AuthClient may guide the user to try again.

The corresponding result.resultCode  and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

  • Common error codes are common for all Mini Program OpenAPIs.  
  • API-specific error codes are listed in the following table.

resultStatus

resultCode

resultMessage

Further Action

F

AUTH_CLIENT_UNSUPPORTED_GRANT_TYPE

The auth client does not support this grant type.

F

INVALID_AUTH_CLIENT

The auth client is invalid.

F

INVALID_AUTH_CLIENT_STATUS

Invalid auth client status.

F

INVALID_REFRESH_TOKEN

The refresh token is invalid.

F

EXPIRED_REFRESH_TOKEN

The refresh token is expired.

F

USED_REFRESH_TOKEN

The refresh token has been used.

F

INVALID_CODE

The authorization code is invalid.

F

USED_CODE

The authorization code has been used.

F

EXPIRED_CODE

The authorization code is expired.

F

REFERENCE_CLIENT_ID_NOT_MATCH

The reference client id does not match.

F

EXPIRED_AGENT_TOKEN

The access token of mini program is expired.

F

INVALID_AGENT_TOKEN

The access token of mini program is invalid.

Sample

The authorization token application is used to exchange the access token based on the code after obtaining the code.

/v2/authorizations/applyToken
  1. The Mini Program calls the my.getAuthCode interface to obtain the authorization code from e-wallet. (Step 1)
  2. The e-wallet returns the authorization code to the Mini Program (Step 7)
  3. The Mini Program sends authorization code to the merchant server (Step 8)
  4. The merchant server calls the applyToken interface to apply for the access token from the e-wallet server and the e-wallet server returns the access token and customer ID to the merchant server. The access token should be kept in the merchant server only, which means that it should not be returned to the Mini Program. (Step 9 and Step 11).

Note: Other steps are covered by the e-wallet.

Request

A. Retrieving accessToken with authCode

copy
{
  "authClientId": "202016726873874774774xxxx",
  "grantType": "AUTHORIZATION_CODE",
  "authCode": "2810111301lGZcM9CjlF91WH00039190xxxx"
}

B. Retrieving accessToken with refreshToken

copy
{
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "2810111301lGZcM9CjlF91WH00039190xxxx"
}
  • authCode is from the my.getAuthCode JS-API, you can obtain the authCode in the success callback. when grantType == AUTHORIZATION_CODE means that we are requesting for the accessToken by the authCode.
  • refreshToken is obtained from the response of the previous accessToken Application call. while grantType == REFRESH_TOKEN means that we are requesting the accessToken by providing the refreshToken.

Response

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"  
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
  "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811xxxx",
  "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
  "customerId":"1000001119398804xxxx"
}
  • result.resultStatus==S shows that the application is successful,
  • AuthClient can make use of accessToken, 281010033AB2F588D14B43238637264FCA5AAF35, to access the user's resource scope before 2019-06-06T12:12:12+08:00[accessTokenExpiryTime].
  • AuthClient  can make use of refreshToken, 2810100334F62CBC577F468AAC87CFC6C9107811, to request for a new accessToken before 2019-06-08T12:12:12+08:00[refreshTokenExpiryTime].