applyToken

2024-12-18 06:59

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 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 SUCCESS 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

Code	Value	Message	Further action
SUCCESS	S	Success	The authorization is completed. Store accessToken and other related fields.
ACCESS_DENIED	F	Access is denied.	Contact Antom Technical Support for detailed reasons.
CLIENT_FORBIDDEN_ACCESS_API	F	The client is not authorized to use this API.	Contact Antom Technical Support for detailed reasons.
INVALID_ACCESS_TOKEN	F	The 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_API	F	The called API is invalid or not active.	Contact Antom Technical Support to resolve the issue.
INVALID_AUTHCODE	F	The 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_STATUS	F	The client status is invalid.	Contact Antom Technical Support for detailed reasons.
INVALID_REFRESH_TOKEN	F	The 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_SIGNATURE	F	The 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: The signature field in a request header How to calculate a signature
KEY_NOT_FOUND	F	The 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_DEF	F	API is not defined.	Check whether the URL is correct. Please refer to the endpoint in the API documentation.
NO_PAY_OPTIONS	F	The 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_FAILED	F	OAuth process failed.	Contact Antom Technical Support for detailed reasons.
PARAM_ILLEGAL	F	The 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_FAIL	F	A 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_ERROR	F	A system error occurred.	Do not retry, and contact Antom Technical Support for more details.
UNKNOWN_CLIENT	F	The client is unknown.	Contact Antom Technical Support for detailed reasons.
USER_NOT_EXIST	F	The user does not exist on the wallet side.	Contact Antom Technical Support for detailed reasons.
USER_STATUS_ABNORMAL	F	The user status is abnormal on the wallet side.	Contact Antom Technical Support to know the specific reasons.
AUTH_IN_PROCESS	U	The authorization is still in process.	Call this interface again until you receive a final result status.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support.
UNKNOWN_EXCEPTION	U	An 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.