createVaultingSession
Use the createVaultingSession API to create a vaulting session for integrating the client-side SDK. Alipay returns the encrypted session data through this API response. You can then use the session data to initiate the client-side SDK. The SDK facilitates 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:
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 about this field
- Maximum length: 64 characters
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.
- Maximum length: 64 characters
vaultingNotificationUrl String REQUIRED
The URL that is used to receive the vaulting result notification.
More information about this field
- Maximum length: 2048 characters
redirectUrl String
The merchant page URL that the buyer is redirected to after the vaulting process is completed.
Specify this parameter if you want to redirect the buyer to your page directly after the vaulting is completed.
More information about this field
- 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.
Specify this parameter when you use the Global Acquirer Gateway (GAGW) product.
More information about this field
- Maximum length: 2 characters
Response parameters
result Result object REQUIRED
The result of the API call.
vaultingSessionData String REQUIRED
The encrypted vaulting session data. Pass the data to your front end to initiate the client-side SDK.
More information about this field
- Maximum length: 4096 characters
vaultingSessionId String REQUIRED
The encrypted ID that is assigned by Alipay to identify a vaulting session.
More information about this field
- Maximum length: 64 characters
vaultingSessionExpiryTime Datetime REQUIRED
The specific date and time after which the vaulting session will expire.
More information about this field
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
Request
Response
Result process logic
After making an API request, Alipay 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 Alipay.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 Alipay 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 Alipay Technical Support. |