inquireVaulting

2026-07-07 02:10

POST /v1/vaults/inquireVaulting

Use this API to inquire about the vaulting status of a payment method.

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 parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:
If the data type of a parameter is Integer and its value is 20, set it as "20".
If the data type of a parameter 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.

More information:

Maximum length: 64 characters

merchantAccountId String

A unique ID to identify a specific merchant account.

Note: Specify this parameter when you use one client ID across multiple locations.

More information:

Maximum length: 64 characters

Response parameters

result Result REQUIRED

Information about the request calling result.

Note: This field does not indicate the vaulting result. This field only indicates whether this interface is called successfully.

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

normalUrl URL

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

Note:
When the value of result.resultStatus is S and the value of vaultingStatus is PROCESSING, 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 URL

The URL scheme that redirects users to open an App in an Android or iOS system when the target App is installed.

Note: When the value of result.resultStatus is S and the value of vaultingStatus is PROCESSING, one or more of the following URLs may be returned: schemeUrl, applinkUrl, and normalUrl.

More information:

Maximum length: 2048 characters

applinkUrl URL

The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. For Android, the URL is a Native App Link. For iOS, the URL is a Universal Link.

Note: When the value of result.resultStatus is S and the value of vaultingStatus is PROCESSING, one or more of the following URLs may be returned: schemeUrl, applinkUrl, and normalUrl.

More information:

Maximum length: 2048 characters

paymentMethodDetail PaymentMethodDetail

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

Note: This parameter is returned when the value of vaultingStatus is SUCCESS.

Show child parameters

vaultingStatus String

Indicates the payment method's vaulting status. Valid values are:

SUCCESS: indicates that the vaulting is successful.
FAIL: indicates that the vaulting failed.
PROCESSING: indicates that the vaulting is under process.

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

More information:

Maximum length: 10 characters

vaultingResultCode String

The result code for the payment method vaulting operation. The value of this parameter depends on the value of vaultingStatus:

If the value of vaultingStatus is SUCCESS, the value is SUCCESS.
If the value of vaultingStatus is PROCESSING, the value is VERIFICATION_IN_PROCESS.
If the value of vaultingStatus is FAIL, the value is a specific error code indicating the reason for the failure. For details, see the Vaulting result codes table.

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

More information:

Maximum length: 64 characters

vaultingResultMessage String

The readable description for vaultingResultCode. The value of this parameter depends on the value of vaultingStatus:

If the value of vaultingStatus is SUCCESS, the value is success.
If the value of vaultingStatus is PROCESSING, the value is The verification is still under process.
If the value of vaultingStatus is FAIL, the value is a specific error code indicating the reason for the failure. For details, see the Vaulting result codes table.

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

More information:

Maximum length: 256 characters

metadata String

Your metadata provided during the vaulting process.

This parameter is returned when you provided value to the parameter in the vaultPaymentMethod API.

More information:

Maximum length: 2048 characters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Method

POST

Request Body

Response

Case

Vaulting successful

Case description

The following response is returned for a successful vaulting:

Response Body

Result process logic

In the response, result.resultStatus indicates the API call result, while vaultingStatus, vaultingResultCode, and vaultingResultMessage indicate the vaulting business result. Handle the response in the following two steps:

Step 1: Check the API call result (result.resultStatus)

Note: vaultingStatus, vaultingResultCode, and vaultingResultMessage are reliable only when result.resultStatus is S. When result.resultStatus is F or U, do not rely on the values of these parameters.

Step 2: Interpret the vaulting business result

Note: This step is valid only when result.resultStatus is S.

*vaultingStatus*	*vaultingResultCode*	Description	Further action
`SUCCESS`	`SUCCESS`	Vaulting successfully.	No further action is needed.
`PROCESSING`	`VERIFICATION_IN_PROCESS`	Vaulting is being processed, for example, 3D Secure verification is in progress.	Guide the user to complete the verification, and then call this API again to query the result.
`FAIL`	Specific error code	Vaulting failed.	Determine the failure reason based on vaultingResultCode and take the corresponding action. For details, see the Vaulting result code list on this page.

API call result codes

*resultCode*	*resultStatus*	*resultMessage*	Further action
`SUCCESS`	`S`	Success.	The API call was successful, no further action is required.
`CLIENT_FORBIDDEN_ACCESS_API`	`F`	The client is not authorized to use this API.	Check the client permission configuration.
`INVALID_API`	`F`	The called API is invalid or not active.	Verify the API name and version.
`INVALID_CLIENT_STATUS`	`F`	The client status is invalid.	Check the merchant onboarding status.
`INVALID_SIGNATURE`	`F`	The signature is not validated. The private key used to sign a request does not match the public key of Antom Dashboard.	Confirm that the signature private key matches the public key configured in the Antom Dashboard.
`KEY_NOT_FOUND`	`F`	The private key or public key of Antom or the merchant is not found.	Validate the public-private key configurations for Antom and the merchant.
`MERCHANT_NOT_REGISTERED`	`F`	The client status is invalid.	Complete the merchant onboarding process first.
`NO_INTERFACE_DEF`	`F`	API is not defined.	Ensure the API path is correct.
`REQUEST_TRAFFIC_EXCEED_LIMIT`	`F`	The request traffic exceeds the limit.	Reduce the request frequency or contact Antom Technical Support to increase the limit.
`VAULTING_NOT_EXIST`	`F`	The vaulting request ID does not exist.	Verify the value of vaultingRequestId. If correct, contact Antom Technical Support for specific details.
`UNKNOWN_EXCEPTION`	`U`	An API call has failed, which is caused by unknown reasons.	Retry the API call to resolve the issue. If the problem persists, contact Antom Technical Support.

Vaulting result codes

*vaultingResultCode*	*vaultingResultMessage*	Further action
`ACCESS_DENIED`	Access denied.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`ACCOUNT_CLOSED`	The account is closed. Please verify the account number for accuracy and do not attempt to process the same PAN or token again.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`AUTHENTICATION_REQUIRED`	3D Secure authentication is required.	Initiate vaulting again and guide the user to complete 3D Secure authentication.
`BLOCKED_FIRST_USED`	When a card is either temporarily blocked, has not been activated for first use, or is subject to special conditions that prevent processing (e.g., new cardholder not activated).	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`CARD_EXPIRED`	Card has expired.	Prompt the user to try again with another card.
`CARD_NOT_SUPPORTED`	Card not supported.	Prompt the user to try again with another card.
`DO_NOT_HONOR`	The payment is declined by the issuing bank.	Prompt the user to try again with another card or contact the card issuer.
`FRAUD_REJECT`	The transaction cannot be further processed for security reasons. If the user has already paid for the transaction, the transaction will be refunded.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`INVALID_CARD_NUMBER`	invalid card number	Prompt the user to check and re-enter the card number.
`INVALID_CVV`	The CVV code is invalid.	Prompt the user to check and re-enter the CVV.
`INVALID_EXPIRATION_DATE`	invalid expiration date	Prompt the user to check and re-enter the expiration date.
`LOST_CARD`	Lost card, pick up card (fraud account)	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`NO_SELECTED_ACCOUNT`	Used when the cardholder has selected specific account but does not have.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`ORDER_IS_CLOSED`	The order is closed.	Initiate a new vaulting request with a new vaultingRequestId.
`PAYMENT_AMOUNT_EXCEED_LIMIT`	Payment amount exceeds limit.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`PAYMENT_COUNT_EXCEED_LIMIT`	Payment count exceeds limit.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`PICKUP_CARD`	The card issuer requests that the merchant retain the card. This typically arises in cases of suspected counterfeit or stolen cards.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`POLICY`	Policy.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`PROCESS_FAIL`	A general business failure occurred. Don't retry.	Do not retry. Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`RESTRICTED_CARD`	The card issuer has imposed restrictions on where the card can be used.	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`STOLEN_CARD`	Stolen card, pick up (fraud account).	Contact Antom Technical Support and provide vaultingRequestId and vaultingResultCode.
`USER_BALANCE_NOT_ENOUGH`	User balance is not enough for this transfer.	Suggest that the user use another payment method or top up the account before trying again.
`USER_PAYMENT_VERIFICATION_FAILED`	User verification like OTP or PIN verified failed.	Prompt the user to verify again.
`VERIFY_TIMES_EXCEED_LIMIT`	Verify code failed too many times, user must get a new code.	Prompt the user to obtain a new verification code.

*result.resultStatus*	Description	Further action
`S`	The API call is successful.	Proceed to Step 2 to interpret the vaulting business result.
`F`	The API call failed.	Do not rely on vaultingStatus, vaultingResultCode, or vaultingResultMessage, as these parameters might not be returned. Identify the failure reason based on result.resultCode.
`U`	The API call result is unknown.	It is recommended to call the API again. If the issue persists, contact Antom Technical Support.