vaultPaymentMethod

2024-12-18 06:59

POST /v1/vaults/vaultPaymentMethod

Use this 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 (Checkout Payment) API, while the URLs can be used to redirect the user to complete the vaulting.

Request parameters

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 REQUIRED

The merchant page URL that the buyer is redirected to after the vaulting process 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

paymentMethodDetail PaymentMethodDetail REQUIRED

The details about the payment method that needs to be vaulted.

Show child parameters

env Env REQUIRED

Information about the environment where the order is placed, such as the device information.

Show child parameters

Response parameters

result Result REQUIRED

The result of the API call.

Show child parameters

vaultingRequestId String REQUIRED

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

More information:

Maximum length: 64 characters

paymentMethodDetail PaymentMethodDetail

The details about the payment method that needs to be vaulted.

Note: This parameter is returned when the value of result.resultStatus is S.

Show child parameters

normalUrl String

The URL that redirects the user to a WAP or WEB page in the default browser or the embedded WebView.

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

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:

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:

Maximum length: 2048 characters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Request Body

Response

Response Body

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 is VERIFICATION_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 Antom 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 Antom 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 Antom Technical Support.
VERIFICATION_FAIL	F	The verification of the payment method information failed.	Call this API again with a new request ID.