# applyToken

> 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 Tokenized Payment.
Use this API to get a new access token via the refresh token when an existing access token is about to expire.

`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**](https://docs.antom.com/ac/ams/authconsult.md) API successfully. The access token will be used when initiating Tokenized Payment.
-   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： 

-   [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur)
-   [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90)

> **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](https://docs.antom.com/ac/pm/enumeration_values.md) 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 parameter is obtained from the reconstructed redirection URL returned by the payment method.

> **Note**: Specify this field when the value of _grantType_ is `AUTHORIZATION_CODE`.

More information:

- Maximum length: 128 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**](https://docs.antom.com/ac/ams/accesstokenapp.md) 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](https://www.iso.org/obp/ui/#search) 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

#### merchantAccountId (String)

A unique ID to identify a specific merchant account.

> **Note**: Specify this parameter when you use one client ID across multiple locations.

More information:

- Maximum length: 64 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.

##### resultCode (String, REQUIRED)

Result code. Possible values are listed in the **Result/Error codes** table on this page.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

Result status. Valid values are: 

-   `S`: Indicates that this API is called successfully and the access token is obtained.
-   `F`: Indicates that this API calling is failed. The access token is not obtained. Retry the process. 
-   `U`: Indicates that the calling status of this API is unknown. Retry the calling process.

##### resultMessage (String, REQUIRED)

Result message that explains the result code.

More information:

- Maximum length: 256 characters

#### 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### userLoginId (String)

The user’s registered login ID for the payment method, which can be an email address or phone number. The value is masked when returned by the payment method and can be used by the merchant to identify registered users.

> **Note**: This parameter is returned when _result.resultCode_ is `SUCCESS` and the _scopes_ parameter in the [**consult**](https://docs.antom.com/ac/ams/authconsult.md) 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

## 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. |

## Request

### AUTH_CODE

```json
{
  "merchantAccountId": "2188234232",
  "authCode": "663A8FA9D83648EE8AA11FF68298XXXX",
  "customerBelongsTo": "GCASH",
  "grantType": "AUTHORIZATION_CODE"
}
```

### REFRESH_TOKEN

```json
{
  "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811",
  "customerBelongsTo": "GCASH",
  "grantType": "REFRESH_TOKEN"
}
```

## Response

### ACCESS_TOKEN_TNG

```json
{
  "accessTokenExpiryTime": "2022-09-14T17:14:16+08:00",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "accessToken": "281011030220200914TLsu9RhgUv87Lf1111****",
  "extendInfo": "{\"userId\":\"100000111111****\",\"userLoginId\":\"6017271****\"}",
  "refreshTokenExpiryTime": "2023-03-16T17:14:16+08:00",
  "refreshToken": "281011111110200914aGT3jbpxci875H0041****",
  "userLoginId": "6017271****"
}
```

### ACCESS_TOKEN_DANA

```json
{
  "accessTokenExpiryTime": "2030-09-12T17:46:11+08:00",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "accessToken": "28101203_QbsH8VmAZcFtAw5W1u255vHaGY8Z2RaFXyV1****",
  "extendInfo": "{\"extendInfo\":\"{}\",\"userId\":\"20200914111215830126DANAW3ID032469616274\",\"userLoginId\":\"62-881****111\"}",
  "refreshTokenExpiryTime": "2030-09-12T17:46:11+08:00",
  "refreshToken": "90k5bheLo6j5UMqcu1cG82sJSS0xpr9GuBz1****",
  "userLoginId": "62-881****111"
}
```

### ACCESS_TOKEN_GCASH

```json
{
  "accessTokenExpiryTime": "2022-09-14T17:46:52+08:00",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "accessToken": "28101003_20200914QCnf0zqtVBbEbxubUaCA0uk9jdH3W6c86BDto7ZYUv4088070561****",
  "extendInfo": "{\"extendInfo\":\"{subMerchantId=1022188000000000001218812000111****, loginId=***-9****35898, acqSiteUserId=21701000000711111****, merchantContractId=202009141907440000082001111****, eventLinkId=9f2f07598e04446aa8646a11f7a1****, subMerchantName=Food Panda Philippines Inc., userId=21701011100717276****}\",\"userId\":\"21701000000111116****\",\"userLoginId\":\"63-9****31111\"}",
  "refreshTokenExpiryTime": "2022-09-14T17:46:52+08:00",
  "refreshToken": "20200914RBDpooYdr88pPVZLB50zWFSbVb2NXbuCZUhGXt9onvH088070561****",
  "userLoginId": "63-9****31111"
}
```

### ACCESS_TOKEN_KAKAOPAY

```json
{
  "accessTokenExpiryTime": "2120-09-14T17:46:54+08:00",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "accessToken": "28100603_at470e8d36786141b28e8d367861a1****",
  "extendInfo": "{\"userId\":\"4b3503f5b08a3eca68408832fa1d34e2b0665ae8b2dc403656f3855359d8****\",\"userLoginId\":\"sh****2@daver.com\"}",
  "userLoginId": "sh****2@daver.com"
}
```

### ACCESS_TOKEN_ALIPAY_HK

```json
{
  "accessTokenExpiryTime": "2038-01-01T08:00:17+08:00",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "accessToken": "281004033282151600076554000zGN1ykLTj48qXUZ00****",
  "extendInfo": "{\"userId\":\"216026507105****\",\"userLoginId\":\"852-97****10\"}",
  "refreshTokenExpiryTime": "2038-01-01T08:00:17+08:00",
  "refreshToken": "28100403POpJutoKNBx5DvhQOZUNj4AeQJ3GDQ1aiB00****",
  "userLoginId": "852-97****10"
}
```

### ACCESS_TOKEN_TRUEMONEY

```json
{
  "accessTokenExpiryTime": "2022-09-11T06:19:39+08:00",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "accessToken": "21111703_55a02a1ad9abbad36efbc59341fc****",
  "extendInfo": "{\"userId\":\"tmn.1003427****\",\"userLoginId\":\"+66*****4902\"}",
  "refreshTokenExpiryTime": "2023-03-12T21:19:39+08:00",
  "refreshToken": "28100703_6bb2e3f62076198a82ba15e2f87f****",
  "userLoginId": "+66*****4902"
}
```