Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

createVaultingSession

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.

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

Response parameters

result Result object REQUIRED

The result of the API call. 

Show child parameters

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 standard format. For example, "2019-11-27T12:01:01+08:00".
API Explorer
Sample CodesRun in Sandbox

Request

URL
Request Body

Response

Response Body

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

CodeValueMessageFurther action
SUCCESSSSuccess

The vaulting session is successfully created. No further action is needed.

PARAM_ILLEGALFThe 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_FAILFA 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_EXCEPTIONUAn 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.