# createVaultingSession

> This API is used to create a vaulting session for client-side SDK integration.

`POST /v1/vaults/createVaultingSession`

This API is used to create a vaulting session for client-side SDK integration. Through this API response, APO 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 initiating a payment.

# 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 payment method type is included in payment method options. See [Payment methods](https://docs.antom.com/ac/apo/payment_methods.md) to check the valid values for card payments.

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:

- Maximum length: 64 characters

#### vaultingNotificationUrl (String)

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

#### passThroughMetadata (String)

A set of key-value pairs that indicate your additional and custom information about the transaction.

> **Note**: Specify this parameter if you want to provide more information about the transaction to your acquirer.

More information:

- Maximum length: 2048 characters

## Response parameters

#### result (Result, REQUIRED)

The result of the API call.

##### resultCode (String, REQUIRED)

Result code. The result code that might be returned 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 the result status is successful.
-   `F`: Indicates that the result status is failed. 
-   `U`: Indicates that the result status is unknown.

##### resultMessage (String, REQUIRED)

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 is assigned by APO 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".

## 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 APO Technical Support to troubleshoot the issue. |
| 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 APO Technical Support. |

## Request

```json
{
  "paymentMethodType": "CARD",
  "vaultingRequestId": "vaultingRequestId_001",
  "vaultingNotificationUrl": "https://www.example.com.sg",
  "redirectUrl": "https://www.example.com",
  "passThroughMetadata": "{\"hitCode\":23166,\"name\":\"xcccc\"}"
}
```

## Response

```json
{
  "vaultingSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "vaultingSessionExpiryTime": "2023-04-06T03:28:49+08:00",
  "vaultingSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
```