# vaultPaymentMethod `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**](https://docs.antom.com/ac/apo/pay.md) 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：  - [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur) - [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90) > **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: - 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](https://www.iso.org/obp/ui/#search) 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. ##### 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 ##### card (Card) The card information. > **Note**: Specify this parameter when all the following conditions are met: > > - You are PCI compliant. > - The value of _paymentMethodType_ is `CARD`. ###### cardNo (String, REQUIRED) The card number. More information: - Maximum length: 32 characters ###### brand (string) Deprecated. Use _selectedCardBrand_ instead. ###### selectedCardBrand (String) The card brand that the user used for payment. See [Card brands](https://docs.antom.com/ac/apo/payment_methods.md#ZfyuE) to check the valid values. > **Note**: Specify this parameter when the card is a co-badged card. If you do not specify this parameter, APO decides which card brand the user uses to pay based on the payment success rate and other factors. More information: - Maximum length: 64 characters ###### cardholderName (UserName) The cardholder's name. > **Note**: Specify this parameter when the card issuing bank is in Brazil, Chile, Mexico, or Peru. ###### firstName (String, REQUIRED) The cardholder's first name. More information: - Maximum length: 32 characters ###### middleName (String) The cardholder's middle name. More information: - Maximum length: 32 characters ###### lastName (String, REQUIRED) The cardholder's last name. ###### fullName (String) The cardholder's full name. More information: - Maximum length: 128 characters ###### billingAddress (Address) The billing address that is associated with the cardholder's card account. > **Note**: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates. ###### region (String, REQUIRED) The 2-letter country or region code. For more information, see the [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard. More information: - Maximum length: 2 characters ###### state (String) The state, country, or province name. > **Note**: For card payments, if your business entity is in the United States, and the card issuing country is Canada, the United States, or the United Kingdom, set the value to a region code that consists of two to three characters and follows the ISO 3166-2 standard. More information: - Maximum length: 8 characters ###### city (String) The city, district, suburb, town, or village name. More information: - Maximum length: 32 characters ###### address1 (String) Address line 1, for example, the street address, PO box, and company name. More information: - Maximum length: 256 characters ###### address2 (String) Address line 2, for example, the apartment, suite, unit, and building information. More information: - Maximum length: 256 characters ###### zipCode (String) The ZIP or postal code. > **Note**: For card payments, if your business entity is in the United States, specify this parameter according to the following parameter value requirements: > > - Only contains numbers, letters, hyphens, and spaces. > - Must be within ten characters. More information: - Maximum length: 32 characters ###### cvv (String) The card verification value (CVV), which is also known as a card security code (CSC) or a card verification code (CVC). > **Note**: Specify this parameter when the card issuing bank is in Brazil, Chile, Mexico, or Peru, or the card is a global card. More information: - Maximum length: 3 characters ###### expiryYear (String, REQUIRED) The year the card expires. Pass in the last two digits of the year number. For example, if the expiration year is 2025, the value of this parameter is `25`. More information: - Maximum length: 2 characters ###### expiryMonth (String, REQUIRED) The month the card expires. Pass in two digits representing the month. For example, if the expiration month is February, the value of this parameter is `02`. More information: - Maximum length: 2 characters ###### dateOfBirth (String) The date of birth of the cardholder. The value of this parameter is an 8-digit date of birth in the format of `YYYY-MM-DD` that follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. For example, `1971-06-07` means the cardholder's birthday is June 7, 1971. > **Note**: Specify this parameter when all the following conditions are met: > > - The card issuing bank is in Korea. > - The card is a personal card. More information: - Maximum length: 10 characters ###### businessNo (String) The business number of the company that holds the corporate card. The value of this parameter is a 10-digit business number, such as 97XXXXXX11. > **Note**: Specify this parameter when all the following conditions are met: > > - The card issuing bank is in Korea. > - The card is a corporate card. More information: - Maximum length: 10 characters ###### cardPasswordDigest (String) The first two digits of the card payment password. > **Note**: Specify this parameter when the card issuing bank is in Korea. More information: - Maximum length: 2 characters ###### cpf (String) The Cadastro Pessoal de Pessoa Física (CPF) is the tax ID of the Brazilian individual taxpayer. > **Note**: Specify this parameter when the card issuing bank is in Brazil. More information: - Maximum length: 11 characters ###### payerEmail (String) The email address of the payer. > **Note**: Specify this parameter when the card issuing bank is in Brazil, Chile, Mexico, or Peru. More information: - Maximum length: 64 characters ###### is3DSAuthentication (Boolean) Indicates whether the transaction authentication type is 3D secure. Specify this parameter when the value of _paymentMethodType_ is `CARD`. #### env (Env, REQUIRED) Information about the environment where the order is placed, such as the device information. ##### terminalType (String, REQUIRED) Terminal type to which the merchant service applies. Valid values are: - `WEB`: The client-side terminal type is a website, which is opened via a PC browser. - `WAP`: The client-side terminal type is a mobile website (H5 page), which is opened via a mobile browser. - `APP`: The client-side terminal type is a mobile application. - `MINI_APP`: The terminal type of the merchant side is a mini program on the mobile phone. ##### osType (String) OS type. Valid values are: - `IOS`: indicates the operation system is Apple's iOS. - `ANDROID`: indicates the operation system is Google's Android. > **Note**: Specify this field when _terminalType_ is not `WEB`. ##### deviceLanguage (String) The language of the device where the user places an order. > **Note**: Specify this parameter if you require risk control. Providing this information helps to identify black-market behavior. More information: - Maximum length: 32 characters ##### deviceId (String) The unique ID of the device the user places an order with. > **Note**: Specify this parameter if you require risk control. This parameter can be used to build a trusted relationship between users and commonly used devices, thereby reducing risk control interruptions and increasing the payment success rate. More information: - Maximum length: 64 characters ##### clientIp (String) The IP address of the client device. > **Note**: Specify this parameter when one of the following conditions is met: > > - You require risk control. > - The value of _paymentMethodType_ is `CARD`. > > Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates. More information: - Maximum length: 64 characters ## Response parameters #### result (Result, REQUIRED) The result of the API call. ##### resultCode (String, REQUIRED) The result code. The possble result codes are listed in the **Result/Error codes** table on this page. More information: - Maximum length: 64 characters ##### resultStatus (String, REQUIRED) The result status. Valid values are: - `S`: indicates that the result status is successful. - `F`: indicates that the result status is failed.  - `U`: indicates that the result status is unknown. ##### resultMessage (String, REQUIRED) Result message that explains the result code. More information: - Maximum length: 256 characters #### 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`. ##### 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 ##### card (Card) The card information. > **Note**: This parameter is returned when the value of _paymentMethodType_ is `CARD` and the value of _result.resultStatus_ is `S`. ###### cardToken (String, REQUIRED) The token of the card. The value of this parameter is used by _paymentMethodId_ in the [**pay**](https://docs.antom.com/ac/apo/pay.md) API when initiating payments. More information: - Maximum length: 2048 characters ###### brand (String) Deprecated. Return _selectedCardBrand_ instead. ###### selectedCardBrand (String, REQUIRED) The card brand that the user used for payment. See [Card brands](https://docs.antom.com/ac/apo/payment_methods.md#ZfyuE) to check the valid values. More information: - Maximum length: 64 characters ###### maskedCardNo (String, REQUIRED) The masked card number, showing only a few digits and hiding the rest. More information: - Maximum length: 64 characters ###### supportedBrands (String) Supported card brands. More information: - Maximum length: 32 characters #### normalUrl (String) The URL that redirects the user to a WAP or WEB page in the default browser or the embedded WebView. > **Notes**: > > - 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 #### acquirerInfo (AcquirerInfo) The information of the acquirer that processes the payment. ##### acquirerName (String) The name of the acquirer. More information: - Maximum length: 64 characters ## 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**](https://docs.antom.com/ac/apo/pay.md) 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 APO 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 APO 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 APO 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 APO Technical Support. | | VERIFICATION_FAIL | F | The verification of the payment method information failed. | Call this API again with a new request ID. | ## Request ```json { "vaultingRequestId": "123456789206", "vaultingNotificationUrl": "www.test.com", "redirectUrl": "www.test.com", "paymentMethodDetail": { "paymentMethodType": "CARD", "card": { "cardNo": "4112273146798764", "brand": "VISA", "cardholderName": { "firstName": "xu", "middleName": "fang", "lastName": "jie", "fullName": "xufangjie" }, "billingAddress": { "region": "CN", "address1": "gongzhuan Road", "city": "hangzhou", "state": "zhejiang", "zipCode": "310000" }, "cvv": "123", "expiryYear": "26", "expiryMonth": "08", "businessRegistrationNo": "96", "is3DSAuthentication": "true" } }, "env": { "terminalType": "app" } } ``` ## Response ```json { "acquirerInfo": { "acquirerName": "ADYEN" }, "paymentMethodDetail": { "card": { "brand": "VISA", "supportedBrands": [ "VISA", "MASTERCARD" ], "cardToken": "ALIPAY9CGwsAeMBug+G2dSKDV6IsNKTxAFNkOMoj8Gxvt8h0eDUbd6nO5CwMFIjEFERWxCAo/b1OjVTvtl1zspyMGcg==", "maskedCardNo": "************8764", "networkTransactionId": "xxxxx" }, "paymentMethodType": "CARD" }, "vaultingRequestId": "123487889889", "vaultingStatus": "SUCCESS", "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ```