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

#### 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 **Result/Error codes** 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

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

This parameter is returned when the value of _result.resultStatus_ is `S`.

More information:

- Maximum length: 10 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

For different request results, different actions must be taken. The possible responses for _result.resultStatus_ are:

-   `S`: indicates the API call succeeded. You can get the vaulting result from _vaultingStatus_ in the API response.
-   `F`: indicates the API call failed. For more information on why the call failed, see _result.resultCode_.
-   `U`: indicates the API call failed due to an unknown reason. Retry using the same request ID.

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | Success | No further action is needed. |
| VAULTING_NOT_EXIST | F | The vaulting request ID does not exist. | Check whether the value of vaultingRequestId is correct. If it is correct, contact Antom Technical Support for specific reasons. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the API again to resolve the issue. If not resolved, contact Antom Technical Support. |

## Request

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

## Response

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