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

applyToken

POST /v1/authorizations/applyToken

Use this API in one of the following ways to complete different tasks: 

  • Use this API to obtain an access token via authCode obtained by calling the consult API successfully. The access token will be used when initiating an auto debit.
  • Use this API to get a new access token via the refresh token when an existing access token is about to expire.

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 String  REQUIRED

The task to complete by using this API. Valid values are:  

  • AUTHORIZATION_CODE: When you want to get the access token, use this value. You can get an access token after calling this API successfully.
  • REFRESH_TOKEN: Each access token has an expiry time that is specified by accessTokenExpiryTime. When your access token is about to expire and you want to get a new access token, use this value. You can get a new access token after calling this API successfully. 

customerBelongsTo String  REQUIRED

The wallet that the customer uses. See Payment methods to check the valid values.  

More information:

  • Maximum length: 64 characters

authCode String  

The authorization code, used for getting an access token. The value of this field is obtained from the reconstructed redirection URL returned by the wallet.

Note: Specify this field when the value of grantType is AUTHORIZATION_CODE.

More information:

  • Maximum length: 64 characters

refreshToken String  

The refresh token, used for getting a new access token when the access token is about to expire. The refresh token is obtained from the response of the successfully called applyToken API.

Note: Specify this field when the value of grantType is REFRESH_TOKEN.

More information:

  • Maximum length: 128 characters

merchantRegion String  

The country or region where the merchant or secondary merchant operates the business. The parameter is a 2-letter country/region code that follows ISO 3166 Country Codes standard. Only US, JP, PK, SG are supported now.

Note: This field is required when you use the Global Acquirer Gateway (GAGW) product. 

More information:

  • Maximum length: 2 characters

Response parameters

result Result object REQUIRED

Indicates whether this API is called successfully. If this API is successfully called, the access token can be obtained.

Show child parameters

accessToken String  

The access token that is used to access the corresponding scope of the user resource. 

Note: This field is returned when the API is called successfully.

More information:

  • Maximum length: 128 characters

accessTokenExpiryTime Datetime  

The time after which the access token expires. After the access token expires, the access token cannot be used to deduct money from the user's account. 

Note: This field is returned when accessToken is returned.

More information:

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

refreshToken String  

The refresh token that is used to exchange for a new access token when the access token is about to expire. 

Note: This field is returned when the wallet supports refreshing the token. If this field is not returned, it indicates that the access token has a quite long valid period.

More information:

  • Maximum length: 128 characters

refreshTokenExpiryTime Datetime  

The time after which the refresh token expires. After the refresh token expires, the refresh token cannot be used to retrieve a new access token. 

Note: This field is returned when refreshToken is returned.

More information:

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

userLoginId String  

The login ID that the user used to register in the wallet. The login ID can be the user's email address or phone number, which is masked when returned to Alipay+ payment methods . This field can inform the merchant of the users who are registered.

Note: This field is returned when result.resultCode is S and the value of the scopes field in the consult API is AGREEMENT_PAY.

More information:

  • Maximum length: 64 characters

extendInfo String  

Extended information.

Note: This field is returned when extended information exists.

More information:

  • Maximum length: 2048 characters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Case
Get accessToken with authCode
Request Body

Response

Case
Touch'n Go
Case description
If you apply for the access token of Touch'n Go, the following response is returned:
Response Body

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, the access token is obtained successfully. Use the access token to access the corresponding user resource scope.
  • If the value of result.resultStatus is U, the access token is not obtained. Retry the process by calling this API again.
  • If the value of result.resultStatus is F, the access token is not obtained. Check the error code and take the corresponding actions. And then retry the process by calling this API again.

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The authorization is completed. Store accessToken and other related fields. 

ACCESS_DENIEDFAccess is denied.

Contact Antom Technical Support for detailed reasons. 

CLIENT_FORBIDDEN_ACCESS_APIFThe client is not authorized to use this API.

Contact Antom Technical Support for detailed reasons.  

INVALID_ACCESS_TOKENFThe access token is expired, revoked, or does not exist.

Check whether accessToken is correct. If not correct, pass in the correct value. If correct, contact Antom Technical Support for detailed reasons.  

INVALID_APIFThe called API is invalid or not active.

Contact Antom Technical Support to resolve the issue.  

INVALID_AUTHCODEFThe authorization code is invalid.

Re-initiate the authorization, call the consult interface to obtain authcode. Contact Antom Technical Support to troubleshoot the issue if the authorization code is correct. 

INVALID_CLIENT_STATUSFThe client status is invalid.

Contact Antom Technical Support for detailed reasons. 

INVALID_REFRESH_TOKENFThe refresh token is invalid.

Use a valid refreshToken to re-initiate the request. Contact Antom Technical Support to troubleshoot the issue if the refresh token is correct. 

INVALID_SIGNATUREFThe signature is not validated. The private key used to sign a request does not match the public key of <span>Antom</span> Dashboard

Check whether the private key used to sign a request matches the public key of Antom Dashboard. The following signature references are useful:

KEY_NOT_FOUNDFThe private key or public key of <span>Antom</span> or the merchant is not found.

Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard. 

NO_INTERFACE_DEFFAPI is not defined.

Check whether the URL is correct. Please refer to the endpoint in the API documentation. 

NO_PAY_OPTIONSFThe payment method is not supported by this API.

Check whether the payment method is a valid value for the customerBelongsTo parameter. If the value you passed in is correct, contact Antom Technical Support for detailed reasons. 

OAUTH_FAILEDFOAuth process failed.

Contact Antom Technical Support for detailed reasons. 

PARAM_ILLEGALFThe required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.

Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. 

PROCESS_FAILFA general business failure occurred.

Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue. 

SYSTEM_ERRORFA system error occurred.

Do not retry, and contact Antom Technical Support for more details. 

UNKNOWN_CLIENTFThe client is unknown.

Contact Antom Technical Support for detailed reasons. 

USER_NOT_EXISTFThe user does not exist on the wallet side.

Contact Antom Technical Support for detailed reasons. 

USER_STATUS_ABNORMALFThe user status is abnormal on the wallet side.

Contact Antom Technical Support to know the specific reasons. 

AUTH_IN_PROCESSUThe authorization is still in process.

Call this interface again until you receive a final result status. 

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. 

UNKNOWN_EXCEPTIONUAn API call has failed, which is caused by unknown reasons.

Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support.