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 about this field
- 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 about this field
- 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 about this field
- 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 about this field
- 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.
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 about this field
- 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 about this field
- 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 about this field
- 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 about this field
- 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+ MPP . 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 about this field
- Maximum length: 64 characters
extendInfo String
Extended information.
Note: This field is returned when extended information exists.
More information about this field
- Maximum length: 2048 characters
Request
Response
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 Alipay Technical Support for detailed reasons. |
| CLIENT_FORBIDDEN_ACCESS_API | F | The client is not authorized to use this API. | Contact Alipay 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 Alipay Technical Support for detailed reasons. |
| INVALID_API | F | The called API is invalid or not active. | Contact Alipay 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 Alipay Technical Support to troubleshoot the issue if the authorization code is correct. |
| INVALID_CLIENT_STATUS | F | The client status is invalid. | Contact Alipay Technical Support for detailed reasons. |
| INVALID_REFRESH_TOKEN | F | The refresh token is invalid. | Use a valid refreshToken to re-initiate the request. Contact Alipay 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 Antom 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_FOUND | F | The private key or public key of Alipay 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 Alipay Technical Support for detailed reasons. |
| OAUTH_FAILED | F | OAuth process failed. | Contact Alipay 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 Alipay Technical Support to troubleshoot the issue. |
| SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Alipay Technical Support for more details. |
| UNKNOWN_CLIENT | F | The client is unknown. | Contact Alipay Technical Support for detailed reasons. |
| USER_NOT_EXIST | F | The user does not exist on the wallet side. | Contact Alipay Technical Support for detailed reasons. |
| USER_STATUS_ABNORMAL | F | The user status is abnormal on the wallet side. | Contact Alipay 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 Alipay 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 Alipay Technical Support. |