# inquireVaulting

> Use this API to inquire about the vaulting status of a payment method.

`POST /v1/vaults/inquireVaulting`

Use this API to inquire about the vaulting status of a payment method.  

# 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 parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:
>
> -   If the data type of a parameter is Integer and its value is `20`, set it as "`20`". 
> -   If the data type of a parameter is Boolean and its value is `true`, set it as "`true`".

## Request parameters

#### vaultingRequestId (String, REQUIRED)

The unique ID that is assigned by a merchant to identify a card vaulting request.

More information about this field

-   This field is an API idempotency field. For vaulting requests that are initiated with the same value of _vaultingRequestId_ and reach a final status of `S` or `F`, the same result is to be returned for the request.

More information:

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

Information about the request calling result.

> **Note**: This field does not indicate the vaulting result. This field only indicates whether this interface is called successfully.

##### resultCode (String, REQUIRED)

The result code. The possible result codes are listed in the [**API call result codes**](#5Bv4g) table on this page.

More information:

- Maximum length: 64 characters

##### resultStatus (REQUIRED)

Result status. Valid values are:

-   `S`: Indicates that this API is called successfully.
-   `F`: Indicates that this API call is failed.
-   `U`: Indicates that the calling status of this API is unknown.

##### resultMessage (String, REQUIRED)

Result message that explains the result code.

More information:

- Maximum length: 256 characters

#### vaultingRequestId (String, REQUIRED)

The unique ID that is assigned by a merchant to identify a card vaulting request.

More information:

- Maximum length: 64 characters

#### normalUrl (URL)

The URL that redirects users to a WAP or WEB page in the default browser or the embedded WebView.

> **Note**:
>
> -   When the value of _result.resultStatus_ is `S` and the value of _vaultingStatus_ is `PROCESSING`, one or more of the following URLs may be returned: _schemeUrl_, _applinkUrl_, and _normalUrl_.  
> -   When the value of _paymentMethodType_ is `CARD`, the user is required to complete the 3DS authentication on the page accessed through this URL.

More information:

- Maximum length: 2048 characters

#### schemeUrl (URL)

The URL scheme that redirects users to open an App in an Android or iOS system when the target App is installed.

> **Note**: When the value of _result.resultStatus_ is `S` and the value of _vaultingStatus_ is `PROCESSING`, one or more of the following URLs may be returned: _schemeUrl_, _applinkUrl_, and _normalUrl_.

More information:

- Maximum length: 2048 characters

#### applinkUrl (URL)

The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. For Android, the URL is a Native App Link. For iOS, the URL is a Universal Link.

> **Note**: When the value of _result.resultStatus_ is `S` and the value of _vaultingStatus_ is `PROCESSING`, one or more of the following URLs may be returned: _schemeUrl_, _applinkUrl_, and _normalUrl_.

More information:

- Maximum length: 2048 characters

#### paymentMethodDetail (PaymentMethodDetail)

The details about the payment method that needs to be vaulted.

> **Note**: This parameter is returned when the value of _vaultingStatus_ is `SUCCESS`.

##### paymentMethodType (String, REQUIRED)

The type of payment method to be vaulted. The value of this parameter is fixed to `CARD`.

More information:

- Maximum length: 64 characters

##### card (Card)

The card information.

> **Note**: This parameter is returned when the value of _paymentMethodType_ is `CARD` and the value of _vaultingStatus_ is `SUCCESS`.

###### cardToken (String, REQUIRED)

The token of the card. The value of this parameter is used by _paymentMethodId_ in the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API when initiating payments.

More information:

- Maximum length: 2048 characters

###### brand (String, REQUIRED)

The name of the card brand. See the [Card brands](https://docs.antom.com/ac/pm/enumeration_values.md#ZfyuE) to check the valid values.

More information:

- Maximum length: 32 characters

###### maskedCardNo (String, REQUIRED)

The masked card number, showing only a few digits and hiding the rest.

More information:

- Maximum length: 64 characters

###### networkTransactionId (String)

The unique ID assigned by the card scheme to identify a transaction.

More information:

- Maximum length: 256 characters

###### funding (String)

The funding type of the card. Valid values are:

-   `CREDIT`: indicates a credit card.
-   `DEBIT`: indicates a debit card.
-   `PREPAID`: indicates a prepaid card.
-   `CHARGE`: indicates a charge card.
-   `DEFERRED_DEBIT`: indicates a deferred debit card.

> **Note**: This parameter is returned when the payment method provides this information.

More information:

- Maximum length: 32 characters

###### issuerName (String)

The issuing bank.

> **Note**: The value of this parameter is consistent with the value of _paymentResultInfo.issuerName_ in [**notifyPayment**](https://docs.antom.com/ac/ams/paymentrn_online.md).

More information:

- Maximum length: 256 characters

###### issuingCountry (String)

The issuing country of the card. The value of this parameter is a 2-letter country code that follows [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard.

> **Note**: This parameter is returned when the payment method provides this information.

More information:

- Maximum length: 2 characters

#### vaultingStatus (String)

Indicates the payment method's vaulting status. Valid values are:

-   `SUCCESS`: indicates that the vaulting is successful. 
-   `FAIL`: indicates that the vaulting failed.
-   `PROCESSING`: indicates that the vaulting is under process.

> **Note**: This parameter is returned when the value of _result.resultStatus_ is `S`.

More information:

- Maximum length: 10 characters

#### vaultingResultCode (String)

The result code for the payment method vaulting operation. The value of this parameter depends on the value of _vaultingStatus_:

-   If the value of _vaultingStatus_ is `SUCCESS`, the value is `SUCCESS`.
-   If the value of _vaultingStatus_ is `PROCESSING`, the value is `VERIFICATION_IN_PROCESS`.
-   If the value of _vaultingStatus_ is `FAIL`, the value is a specific error code indicating the reason for the failure. For details, see the [**Vaulting result codes**](#2yHFI) table.

> **Note**: This parameter is returned when the value of _result.resultStatus_ is `S`.

More information:

- Maximum length: 64 characters

#### vaultingResultMessage (String)

The readable description for _vaultingResultCode_. The value of this parameter depends on the value of _vaultingStatus_:

-   If the value of _vaultingStatus_ is `SUCCESS`, the value is `success`.
-   If the value of _vaultingStatus_ is `PROCESSING`, the value is `The verification is still under process`.
-   If the value of _vaultingStatus_ is `FAIL`, the value is a specific error code indicating the reason for the failure. For details, see the [**Vaulting result codes**](#2yHFI) table.

> **Note**: This parameter is returned when the value of _result.resultStatus_ is `S`.

More information:

- Maximum length: 256 characters

#### metadata (String)

Your metadata provided during the vaulting process.

> This parameter is returned when you provided value to the parameter in the [**vaultPaymentMethod**](https://docs.antom.com/ac/ams/vault_method.md) API.

More information:

- Maximum length: 2048 characters

## Result process logic

In the response, _result.resultStatus_ indicates the API call result, while _vaultingStatus_, _vaultingResultCode_, and _vaultingResultMessage_ indicate the vaulting business result. Handle the response in the following two steps:

**Step 1: Check the API call result (****_result.resultStatus_****)**

| **_result.resultStatus_** | **Description** | **Further action** |
| --- | --- | --- |
| `S` | The API call is successful. | Proceed to Step 2 to interpret the vaulting business result. |
| `F` | The API call failed. | Do not rely on _vaultingStatus_, _vaultingResultCode_, or _vaultingResultMessage_, as these parameters might not be returned. Identify the failure reason based on _result.resultCode_. |
| `U` | The API call result is unknown. | It is recommended to call the API again. If the issue persists, contact Antom Technical Support. |

> **Note**: _vaultingStatus_, _vaultingResultCode_, and _vaultingResultMessage_ are reliable only when _result.resultStatus_ is `S`. When _result.resultStatus_ is `F` or `U`, do not rely on the values of these parameters.

**Step 2: Interpret the vaulting business result**

> **Note**: This step is valid only when _result.resultStatus_ is `S`.

| **_vaultingStatus_** | **_vaultingResultCode_** | **Description** | **Further action** |
| --- | --- | --- | --- |
| `SUCCESS` | `SUCCESS` | Vaulting successfully. | No further action is needed. |
| `PROCESSING` | `VERIFICATION_IN_PROCESS` | Vaulting is being processed, for example, 3D Secure verification is in progress. | Guide the user to complete the verification, and then call this API again to query the result. |
| `FAIL` | Specific error code | Vaulting failed. | Determine the failure reason based on _vaultingResultCode_ and take the corresponding action. For details, see the **Vaulting result code** list on this page. |

## API call result codes

| **_resultCode_** | **_resultStatus_** | **_resultMessage_** | **Further action** |
| --- | --- | --- | --- |
| `SUCCESS` | `S` | Success. | The API call was successful, no further action is required. |
| `CLIENT_FORBIDDEN_ACCESS_API` | `F` | The client is not authorized to use this API. | Check the client permission configuration. |
| `INVALID_API` | `F` | The called API is invalid or not active. | Verify the API name and version. |
| `INVALID_CLIENT_STATUS` | `F` | The client status is invalid. | Check the merchant onboarding status. |
| `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. | Confirm that the signature private key matches the public key configured in the Antom Dashboard. |
| `KEY_NOT_FOUND` | `F` | The private key or public key of Antom or the merchant is not found. | Validate the public-private key configurations for Antom and the merchant. |
| `MERCHANT_NOT_REGISTERED` | `F` | The client status is invalid. | Complete the merchant onboarding process first. |
| `NO_INTERFACE_DEF` | `F` | API is not defined. | Ensure the API path is correct. |
| `REQUEST_TRAFFIC_EXCEED_LIMIT` | `F` | The request traffic exceeds the limit. | Reduce the request frequency or contact Antom Technical Support to increase the limit. |
| `VAULTING_NOT_EXIST` | `F` | The vaulting request ID does not exist. | Verify the value of _vaultingRequestId_. If correct, contact Antom Technical Support for specific details. |
| `UNKNOWN_EXCEPTION` | `U` | An API call has failed, which is caused by unknown reasons. | Retry the API call to resolve the issue. If the problem persists, contact Antom Technical Support. |

## Vaulting result codes

| **_vaultingResultCode_** | **_vaultingResultMessage_** | **Further action** |
| --- | --- | --- |
| `ACCESS_DENIED` | Access denied. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `ACCOUNT_CLOSED` | The account is closed. Please verify the account number for accuracy and do not attempt to process the same PAN or token again. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `AUTHENTICATION_REQUIRED` | 3D Secure authentication is required. | Initiate vaulting again and guide the user to complete 3D Secure authentication. |
| `BLOCKED_FIRST_USED` | When a card is either temporarily blocked, has not been activated for first use, or is subject to special conditions that prevent processing (e.g., new cardholder not activated). | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `CARD_EXPIRED` | Card has expired. | Prompt the user to try again with another card. |
| `CARD_NOT_SUPPORTED` | Card not supported. | Prompt the user to try again with another card. |
| `DO_NOT_HONOR` | The payment is declined by the issuing bank. | Prompt the user to try again with another card or contact the card issuer. |
| `FRAUD_REJECT` | The transaction cannot be further processed for security reasons. If the user has already paid for the transaction, the transaction will be refunded. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `INVALID_CARD_NUMBER` | invalid card number | Prompt the user to check and re-enter the card number. |
| `INVALID_CVV` | The CVV code is invalid. | Prompt the user to check and re-enter the CVV. |
| `INVALID_EXPIRATION_DATE` | invalid expiration date | Prompt the user to check and re-enter the expiration date. |
| `LOST_CARD` | Lost card, pick up card (fraud account) | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `NO_SELECTED_ACCOUNT` | Used when the cardholder has selected specific account but does not have. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `ORDER_IS_CLOSED` | The order is closed. | Initiate a new vaulting request with a new _vaultingRequestId_. |
| `PAYMENT_AMOUNT_EXCEED_LIMIT` | Payment amount exceeds limit. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `PAYMENT_COUNT_EXCEED_LIMIT` | Payment count exceeds limit. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `PICKUP_CARD` | The card issuer requests that the merchant retain the card. This typically arises in cases of suspected counterfeit or stolen cards. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `POLICY` | Policy. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `PROCESS_FAIL` | A general business failure occurred. Don't retry. | Do not retry. Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `RESTRICTED_CARD` | The card issuer has imposed restrictions on where the card can be used. | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `STOLEN_CARD` | Stolen card, pick up (fraud account). | Contact Antom Technical Support and provide _vaultingRequestId_ and _vaultingResultCode_. |
| `USER_BALANCE_NOT_ENOUGH` | User balance is not enough for this transfer. | Suggest that the user use another payment method or top up the account before trying again. |
| `USER_PAYMENT_VERIFICATION_FAILED` | User verification like OTP or PIN verified failed. | Prompt the user to verify again. |
| `VERIFY_TIMES_EXCEED_LIMIT` | Verify code failed too many times, user must get a new code. | Prompt the user to obtain a new verification code. |

## Request

```json
{
  "merchantAccountId": "2188234232",
  "vaultingRequestId": "12345678****"
}
```

## Response

### VAULTING_SUCCESSFUL

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "vaultingRequestId": "GIL0026052214509000880104315355",
  "vaultingStatus": "SUCCESS",
  "vaultingResultCode": "SUCCESS",
  "vaultingResultMessage": "success.",
  "paymentMethodDetail": {
    "paymentMethodType": "CARD",
    "card": {
      "brand": "VISA",
      "cardToken": "ALIPAY9CGwsAeMBug+G2dSKDV6AIsNKTxAFNkOMoj8Gxvt8h0eDUbd6nO5CwMFIjEFERWxCAo/b1OjVTvtl1zspyMGcg==",
      "maskedCardNo": "************8764",
      "networkTransactionId": "xxxxx"
    }
  }
}
```

### VAULTING_FAILED

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "vaultingRequestId": "GIL0026052214509000880104315355",
  "vaultingStatus": "FAIL",
  "vaultingResultCode": "CARD_EXPIRED",
  "vaultingResultMessage": "Card has expired."
}
```

### VAULTING_IN_PROCESS

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "vaultingRequestId": "GIL0026052214509000880104315355",
  "vaultingStatus": "PROCESSING",
  "vaultingResultCode": "VERIFICATION_IN_PROCESS",
  "vaultingResultMessage": "The verification is still under process.",
  "normalUrl": "https://www.example.com/3ds-verify"
}
```