# createVaultingSession

> This API is used to create a vaulting session for client-side SDK integration. Through this API response, Antom returns encrypted session data. You use the session data to initiate the client-side SDK. The SDK helps you complete the card vaulting process before a payment is initiated.

`POST /v1/vaults/createVaultingSession`

This API is used to create a vaulting session for client-side SDK integration. Through this API response, Antom returns encrypted session data. You use the session data to initiate the client-side SDK. The SDK helps you complete the card vaulting process before a payment is initiated.

# 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

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

#### vaultingRequestId (String, REQUIRED)

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

More information:

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

#### vaultingNotificationUrl (String, REQUIRED)

The URL that is used to receive the vaulting result notification.

More information:

- Maximum length: 2048 characters

#### redirectUrl (String)

The merchant page URL that the buyer is redirected to after the vaulting is completed.

> Note: Specify this parameter if you want to redirect the buyer to your page directly after the vaulting is completed.

More information:

- Maximum length: 2048 characters

#### merchantRegion (String)

The country or region where the merchant operates the business. The value of this parameter is a 2-letter country or region code based on the [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard.

Some possible values are `US`, `SG`, `HK`, `PK`, `JP`, `CN`, `BR`, `AU`, and `MY`.

> Note: Specify this parameter when you use the Global Acquirer Gateway (GAGW) product.

More information:

- Maximum length: 2 characters

#### is3DSAuthentication (Boolean)

Indicates whether the transaction authentication type is 3D secure. Specify this parameter when the value of _paymentMethodType_ is `CARD`.

## Response parameters

#### result (Result, REQUIRED)

The result of the API call. If this API is successfully called, it means the vaulting session is created 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 (String, REQUIRED)

The result status. Valid values are:

-   `S`: indicates that the result status is successful.
-   `F`: indicates that the result status is failed. 
-   `U`: indicates that the result status is unknown.

##### resultMessage (String, REQUIRED)

The result message that explains the result code.

More information:

- Maximum length: 256 characters

#### vaultingSessionData (String, REQUIRED)

The encrypted vaulting session data. Pass the data to your front end to initiate the client-side SDK.

More information:

- Maximum length: 4096 characters

#### vaultingSessionId (String, REQUIRED)

The encrypted ID that is assigned by Antom to identify a vaulting session.

More information:

- Maximum length: 64 characters

#### vaultingSessionExpiryTime (Datetime, REQUIRED)

The specific date and time after which the vaulting session will expire.

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

#### normalUrl (String)

The URL used to redirect to the card-binding page.

More information:

- Maximum length: 2048 characters

Result process logic 

After making an API request, Antom responds to you with the result of the API call. The possible responses for _result.resultStatus_ are:

-   `S`: indicates the API call succeeded. Get the vaulting status of the payment method by calling the [**inquireVaulting**](https://global.alipay.com/docs/ac/ams/inquire_vaulting) API or waiting for the notification from Antom.
-   `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 | The vaulting session is successfully created. No further action is needed. |
| 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. |
| 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

```json
{
  "paymentMethodType": "CARD",
  "vaultingRequestId": "vaultingRequestId_001",
  "vaultingNotificationUrl": "https://www.google.com.sg",
  "redirectUrl": "https://www.baidu.com",
  "is3DSAuthentication": "false"
}
```

## Response

```json
{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "success."
  },
  "normalUrl": "https://checkout.antom.com/checkout-page/pages/valuting/index.html?sessionData=JXaKw9OzwqMCX0Q9Cd/WVZqjsvPV9xjG06ipXSvLyU5uG8G/wec5mgVWsKl5znfpgbOOylNuVQYCjn8DUrTQaw==&&SG&&188&&eyJleHRlbmRJbmZvIjoieyAgIFwiZW5hYmxlVmF1bHRpbmdBcGlPcHRpbWl6ZVwiOiB0cnVlLCAgIFwic2RrVXBncmFkZUluZm9cIjogeyAgICAgXCJ2ZXJzaW9uc1wiOiBbICAgICAgIHsgICAgICAgICBcImFwcFZlcnNpb25cIjogXCIxLjE0LjBcIiwgICAgICAgICBcInByb2R1Y3RTY2VuZVwiOiBcIlZBVUxUSU5HXCIsICAgICAgICAgXCJ2XCI6IFwiMS4xMy4wfDEuMTQuMFwiICAgICAgIH0gICAgIF0gICB9IH0iLCJwYXltZW50U2Vzc2lvbkNvbmZpZyI6eyJwYXltZW50TWV0aG9kQ2F0ZWdvcnlUeXBlIjoiQ0FSRCIsInByb2R1Y3RTY2VuZSI6IlZBVUxUSU5HIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJza2lwUmVuZGVyUGF5bWVudE1ldGhvZCI6ZmFsc2V9",
  "vaultingSessionData": "JXaKw9OzwqMCX0Q9Cd/WVZqjsvPV9xjG06ipXSvLyU5uG8G/wec5mgVWsKl5znfpgbOOylNuVQYCjn8DUrTQaw==&&SG&&188&&eyJleHRlbmRJbmZvIjoieyAgIFwiZW5hYmxlVmF1bHRpbmdBcGlPcHRpbWl6ZVwiOiB0cnVlLCAgIFwic2RrVXBncmFkZUluZm9cIjogeyAgICAgXCJ2ZXJzaW9uc1wiOiBbICAgICAgIHsgICAgICAgICBcImFwcFZlcnNpb25cIjogXCIxLjE0LjBcIiwgICAgICAgICBcInByb2R1Y3RTY2VuZVwiOiBcIlZBVUxUSU5HXCIsICAgICAgICAgXCJ2XCI6IFwiMS4xMy4wfDEuMTQuMFwiICAgICAgIH0gICAgIF0gICB9IH0iLCJwYXltZW50U2Vzc2lvbkNvbmZpZyI6eyJwYXltZW50TWV0aG9kQ2F0ZWdvcnlUeXBlIjoiQ0FSRCIsInByb2R1Y3RTY2VuZSI6IlZBVUxUSU5HIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJza2lwUmVuZGVyUGF5bWVudE1ldGhvZCI6ZmFsc2V9",
  "vaultingSessionId": "JXaKw9OzwqMCX0Q9Cd/WVZqjsvPV9xjG06ipXSvLyU5/XHyXwQfKASEnfLUMCkzc",
  "vaultingSessionExpiryTime": "2025-04-24T18:17:16+08:00"
}
```