vaultPaymentMethod
Use the vaultPaymentMethod API to vault a payment method prior to initiating a payment. From the API response, you can obtain cardToken or one or more of normalUrl, schemeUrl, or applinkUrl. cardToken is used to initiate payments using the pay API, while the URLs can be used to redirect the user to complete the vaulting.
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
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 REQUIRED
The merchant page URL that the buyer is redirected to after the vaulting process 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
paymentMethodDetail PaymentMethodDetail object REQUIRED
The details about the payment method that needs to be vaulted.
env Env object REQUIRED
Information about the environment where the order is placed, such as the device information.
Response parameters
result Result object REQUIRED
The result of the API call.
vaultingRequestId String REQUIRED
The unique ID that is assigned by a merchant to identify a card vaulting request.
More information about this field
- Maximum length: 64 characters
paymentMethodDetail PaymentMethodDetail object
The details about the payment method that needs to be vaulted.
This parameter is returned when the value of result.resultStatus is S.
normalUrl String
The URL that redirects the user to a WAP or WEB page in the default browser or the embedded WebView.
When the value of result.resultCode is VERIFICATION_IN_PROCESS, 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 about this field
- Maximum length: 2048 characters
schemeUrl String
The URL scheme that redirects the user to open an app in an Android or iOS system when the target app is installed.
More information about this field
- Maximum length: 2048 characters
applinkUrl String
The URL that redirects the user to open an app when the target app is installed, or to open a WAP page when the target app is not installed.
More information about this field
- Maximum length: 2048 characters
Request
Response
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. Obtain cardToken from the response in this API. Then use the value of cardToken in the pay API when initiating payments.F: indicates the API call failed. For more information on why the call failed, see result.resultCode.U: When this value is returned, take action depending on whether or not the value of resultCode isVERIFICATION_IN_PROCESS:- Result code is not
VERIFICATION_IN_PROCESS: The API call fails. Call this API again with a new vaultingRequestId value. - Result code is
VERIFICATION_IN_PROCESS: Check whether one or more of the three URLs (appLinkUrl, normalUrl, schemeUrl) are returned: - one or more of the URLs returned: The vaulting is created successfully. Redirect your user to the specific URL provided to complete the vaulting.
- no URLs returned: The vaulting creation fails. Call this API again with a new vaultingRequestId value. If the issue persists, contact Alipay Technical Support.
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. |
| VERIFICATION_IN_PROCESS | U | The verification of the payment method information is under process. | Get any of the URLs (appLinkUrl, normalUrl, schemeUrl) and open the URL. If no URL is returned, call this API again with a new request ID. If the issue persists, contact Alipay Technical Support. |
| VERIFICATION_FAIL | F | The verification of the payment method information failed. | Call this API again with a new request ID. |