# Store a card using Antom SDK > This article guides you through Antom SDK to learn about the pre-built UI component for merchants. Antom SDK is a pre-built UI component designed to collect card information and manage 3D authentication processes for merchants. Integration of the component does not require merchants to be PCI-eligible, making it ideal for those who prefer to entrust Antom to collect card information. # User experience The following figures show the user journey of vaulting on a shopping website or mobile web app: #### Tab: Web ## Web user experience ![SDK-BindCard-PC.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1718869638105-64b07c44-e3bd-4712-ac21-6934ce6fbac6.png) #### Tab: WAP ## WAP user experience ![SDK-BindCard-Mob.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1718869702071-d0813e4a-6ead-4876-b38f-75db03ee9551.png) # Vaulting flow For each payment method, the vaulting flow is composed of the following steps: ![绑卡SDKen.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/png/21f6a63b-8927-4e4e-b55b-c0f9a85c9d57.png) 1. The buyer lands on the checkout page. 2. Your server creates a vaulting session. 3. Your client creates and invokes the Component with the vaulting session. 4. The component collects card information from the buyer. 5. Your server receives vaulting result notifications. # Integration steps Start your integration by taking the following steps. 1. Create a vaulting session 2. Create and invoke the SDK 3. Obtain vaulting result ## Step 1: Create a vaulting session Server-side When a buyer selects a payment method provided by Antom, you need to collect key information such as the vaulting request ID, vaulting redirect page URL, vaulting result notification URL, etc. and call the [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API to create a vaulting session and return the vaulting session to the client. Antom provides a multi-language server-side API library and follow the steps below with Java (Java 6 or higher) as an example. ### Install an API library You can find the latest version on [GitHub](https://github.com/alipay/global-open-sdk-java). ```xml com.alipay.global.sdk global-open-sdk-java 2.0.44 ``` ### Initialize the request instance Create a singleton resource to make a request to Antom. ```java import com.alipay.global.api.AlipayClient; import com.alipay.global.api.DefaultAlipayClient; import com.alipay.global.api.model.constants.EndPointConstants; public class Sample { public static final String CLIENT_ID = ""; public static final String ANTOM_PUBLIC_KEY = ""; public static final String MERCHANT_PRIVATE_KEY = ""; private final static AlipayClient CLIENT = new DefaultAlipayClient( EndPointConstants.SG, MERCHANT_PRIVATE_KEY, ANTOM_PUBLIC_KEY, CLIENT_ID); } ``` ### Create a vaulting session Creating a vaulting session involves the following parameters: | **Parameter name** | **Required** | **Description** | | --- | --- | --- | | _paymentMethodType_ | Yes | The payment method that you needs to bind. | | _vaultingRequestId_ | Yes | Unique ID generated by the merchant, a new ID is required each time a vaulting session is initiated. | | _vaultingNotificationUrl_ | Yes | The notification address of the vaulting result. | | _redirectUrl_ | No | The URL to jump to after the vaulting is completed. | The above parameters are the basic parameters for creating a payment session, for full parameters and additional requirements for certain payment methods please refer to [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md)**.** #### Sample codes of calling the createVaultingSession API The following sample code shows how to call the [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API: ```java public static void createVaultingSession(){ AlipayVaultingSessionRequest alipayVaultingSessionRequest = new AlipayVaultingSessionRequest(); // replace to your paymentRequestId String vaultingRequestId = UUID.randomUUID().toString(); alipayVaultingSessionRequest.setVaultingRequestId(vaultingRequestId); alipayVaultingSessionRequest.setPaymentMethodType("CARD"); alipayVaultingSessionRequest.setVaultingNotificationUrl("http://www.yourNotifyUrl.com"); alipayVaultingSessionRequest.setRedirectUrl("http://www.yourRedirectUrl.com"); // do vaulting AlipayVaultingSessionResponse alipayVaultingSessionResponse; try{ alipayVaultingSessionResponse = CLIENT.execute(alipayVaultingSessionRequest); }catch (AlipayApiException e){ String errorMsg = e.getMessage(); // handle error condition } } ``` The following code shows a sample of the request message: ```json { "paymentMethodType": "CARD", "redirectUrl": "http://www.yourRedirectUrl.com", "vaultingNotificationUrl": "http://www.yourNotifyUrl.com", "vaultingRequestId": "4a17609d-1749-4f53-a2fb-8bdba8d5aad8" } ``` The following code shows a sample of the response, which contains the following parameters: - _vaultingSessionData_: the vaulting session to be returned to the frontend. - _vaultingSessionExpiryTime_: the expiration time of the vaulting session. ```json { "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" }, "vaultingSessionData": "qOnxVjFYB/QNieiGGnf3P7XOreGIRi7dSZDMzCzT5DzGLaI5a5paDhEAgmG8IwVuTCHscscPdJg==&&SG&&188&&eyJleHRlbmRJbmZvIjoie1widmVyc2lvbk1hcFwiOntcIndlYlwiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcImlPU1wiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcIkFuZHJvaWRcIjp7XCIxLjEuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMS4wXCJ9LFwiMS4yLjBcIjp7XCJ0YXJnZXRXZWJWZXJpc29uXCI6XCIxLjIuMFwifX19fSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJDQVJEIiwicHJvZHVjdFNjZW5lIjoiVkFVTFRJTkciLCJwcm9kdWN0U2NlbmVWZXJzaW9uIjoiMS4wIn0sInNraXBSZW5kZXJQYXltZW50TWV0aG9kIjpm******", "vaultingSessionExpiryTime": "2024-12-31T12:06:05+08:00", "vaultingSessionId": "********qOnxVjFYB/QNieiGGnf3P7XOreGIRi7fAxqpLf+1appjsXAs5Eq1H" } ``` > **Common questions** > > **Q: How to set the vaulting result notification address?** > > A: The vaulting result will be [notified](https://global.alipay.com/docs/ac/ams/paymentrn_online) to you via [**notifyVaulting**](https://docs.antom.com/ac/ams/notify_vaulting.md) API. The URL can be passed in through the _vaulting__NotifyUrl_ parameter in the [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API. ## Step 2: Create and invoke the SDK Client-side The Antom SDK is a component used for handling vaulting processes. You initiate the SDK by creating a vaulting session to collect information and switch between apps based on the payment method specified in [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API. ### Install Before beginning the integration, make sure that you have completed the following environment preparations: - Properly handle compatibility issues: Provide corresponding polyfills for Internet Explorer and other old browser versions. We recommend that you use [babel-preset-env](https://babeljs.io/docs/en/babel-preset-env) to address browser compatibility issues when you build a project. - Use the following recommended browser versions: - For mobile browsers: - iOS 11 and later. - Android 5.0 and later. - For computer browsers, use the following recommended versions: | [![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1680143117412-8322ebf3-b84b-48d1-a696-5cc5703d1006.png)](http://godban.github.io/browsers-support-badges/)**Edge** Lastest 2 versions | [![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1680143117377-62f319d6-72e5-4555-aacd-f0efc434ef9e.png)](http://godban.github.io/browsers-support-badges/)**Firefox** Lastest 2 versions | [![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1680143118111-1392b868-4947-4d0f-941c-53d54c655c8d.png)](http://godban.github.io/browsers-support-badges/)**Chrome** Lastest 2 versions | [![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1680143118162-1fc223a0-8a35-488f-91aa-5833f5d7726a.png)](http://godban.github.io/browsers-support-badges/)**Safari** Lastest 2 versions | [![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1680143118154-fc609c28-81bf-4442-985b-fdf4d1c3554d.png)](http://godban.github.io/browsers-support-badges/)**Opera** Lastest 2 versions | [![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1680143118867-73ee0c65-fbf2-4ff3-b18e-8fa092801c30.png)](http://godban.github.io/browsers-support-badges/)**Electron** Lastest 2 versions | | --- | --- | --- | --- | --- | --- | To integrate the SDK package, refer to [Integrate the SDK Package for Web/WAP](https://docs.antom.com/ac/sdks/web_en.md). ### Instantiate the SDK Create the SDK instance by using the `AMSVaulting` and specify basic configurations. Configuration objects includes the following parameters: | **Parameter name** | **Required** | **Description** | | --- | --- | --- | | _locale_ | No | It is used to pass in language information. Valid values are listed as follows. You can choose the value to pass based on the region of the payment method. If other values are passed, English is used by default: - `en_US`: English - `es_ES`: Spanish - `fr_FR`: French - `nl_NL`: Dutch - `it_IT`: Italian - `de_DE`: German - `zh_CN`: Simplified Chinese | | _environment_ | Yes | It is used to pass in environmental information. Valid values are: - `sandbox`: Sandbox environment - `prod`: Production environment | | _analytics_ | No | It is used to configure and analyze data. It contains a value below: - _enabled_: Optional Boolean. It defaults to true, which indicates that you allow the SDK to upload and analyze operational data to deliver a better service. If you do not allow the data to be uploaded and analyzed, specify it as `false`. | | _onLog_ | No | It is a callback method that is used to generate the error information about logs and API exceptions during the execution of the SDK. | | _onEventCallback_ | No | A callback function returns a specific event code when a payment event happens during SDK runtime, like payment result or a form submission error. | The following sample code shows how to obtain the browser language: ```javascript let language = navigator.language || navigator.userLanguage; language = language.replace("-", "_"); // Replace "-" with "_" ``` The following sample code shows how to instantiate the SDK: ```javascript const checkoutApp = new window.AMSCashierPayment({ environment: "sandbox", locale: "en_US", onLog: ({code, message}) => {}, onEventCallback: ({code, message}) => {}, }); ``` ### Invoke the SDK component After buyers select a payment method on the page, you need to create the vaulting session to invoke the SDK component. Use the `createComponent` or `mountComponent` function in the instance object to create a vaulting component: | **Parameter name** | **Required** | **Description** | | --- | --- | --- | | _sessionData_ | Yes | Create a configuration object by using _sessionData_ parameter: Pass the complete data in _vaultingSessionData_ parameter obtained in the response of the [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API to _sessionData_ parameter. | | _appearance_ | No | Customized appearance theme configuration, and it contains the following child parameters: - _showSubmitButton_: Optional. Boolean type. The default value is `false`, which disables the button to render the payment page. | | _notRedirectAfterComplete_ | No | Boolean type. Valid values are: - `false`: Default value. Indicates that it will redirect to your page after the vaulting is completed. The same applies when the value is empty. - `true`: Indicates that there will be no redirection. You need to monitor the subsequent process after the vaulting is completed through client-side event codes. Note that the result and event codes returned by the client-side are only used as a reference for the redirection operation of the client page. For transaction status updates, refer to the results returned by the server's [**notifyVaulting**](https://docs.antom.com/ac/ams/notify_vaulting.md) or [**inquireVaulting**](https://docs.antom.com/ac/ams/inquire_vaulting.md) API. | #### Embedded experience vs. Popup experience There are different ways in which you can make the Component display on a page through a pop-up window or embedded on a page. | **Embedded experience** | **Popup experience** | | --- | --- | | ![embed.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/png/85eeec2b-8373-4309-859a-904dba2ea328.png) | ![绑卡SDK1.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/png/e6f62529-8fa7-4bbe-9642-817ff678ff23.png) | **Popup experience** Popup experience offers the advantage of low impact on page style and relatively independent flow. After the buyer selects a payment method on the page and clicks submit, the Component needs to be evoked, and the interaction popup will be rendered after loading. ```java async function create(sessionData) { await checkoutApp.createComponent({ sessionData: sessionData, appearance:{ notRedirectAfterComplete: true, }); } ``` **Embedded experience** The embedded experience involves rendering embedded element content within the designated view, so it's essential to focus on styling adjustments for the payment list. Our embedded content's width adjusts automatically to fit the parent container, while the height dynamically updates with view changes. ```javascript async function create(sessionData) { await checkoutApp.mountComponent({ sessionData: sessionData, appearance:{ showSubmitButton: false, // Configure whether the payment button is rendered by the component. }, notRedirectAfterComplete: true, },'#ContainerNodeId'); } ``` **Embedded submit** When using embedded rendering and a custom submit button, remember to actively call the submit function to initiate the submission process. ```javascript // Execute when the buyer completes the form and clicks the submit button. checkoutApp.submit().then(({code, message})=>{}) ``` Call the `unmount` method to free SDK component resources in the following situations: - If your client has set a timeout when the set timeout is reached. - When the buyer exits the card binding page. - When you receive a callback for the card binding result. ```javascript // Free SDK component resources checkoutApp.unmount(); ``` > **Common questions** > > **Q: What can I do when I receive** **SDK\_ASSET\_BINDING\_ERROR** **or a rendering view error occurred?** > > A: Check the network request for any exceptions during interface initialization, such as network timeouts. Ensure that the environment for creating vaulting session request is consistent with the environment used for SDK instantiation. Check whether the parameters in the [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API are passed correctly. If the interface exceptions persist, feel free to contact us for further troubleshooting. ## Step 3: Display vaulting results If you set _notRedirectAfterComplete_ to `false`, the buyer will be redirected to the _vaultingRedirectUrl_ that you provided in [**createVaultingSession**](https://docs.antom.com/ac/ams/vaulting_session.md) API after completing the vaulting. You can obtain the vaulting result by active query in that URL and show it to the buyer. If _notRedirectAfterComplete_ is `true`, the vaulting result will be given through the `onEventCallback` function. The vaulting result here is only for front-end display, and the final order status is subject to the server side. You need to customize the processing flow you want for each vaulting result through the data in the result of `onEventCallback`. The following are the possible event codes of the vaulting result returned by `onEventCallback`: | **Event code** | **Message** | **Solution** | | --- | --- | --- | | SDK\_ASSET\_BINDING\_SUCCESSFUL | Vaulting was successful. | Suggest redirecting buyers to the vaulting result page. | | SDK\_ASSET\_BINDING\_PROCESSING | Vaulting was being processed. | Guide buyers to retry the vaulting based on the provided information. | | SDK\_ASSET\_BINDING\_FAIL | Vaulting failed. | You can follow the vaultingResultCode error code prompt message and redirect the buyer to bind the card. | | SDK\_ASSET\_BINDING\_CANCEL | The buyer exits the vaulting page without submitting the order. | The SDK can be re-invoked with a _vaulting__SessionData_ within the validity period; if it has expired, the _vaulting__SessionData_ needs to be re-requested. | | SDK\_ASSET\_BINDING\_ERROR | The vaulting status was abnormal. | You can wait for the notification of the card binding result or re-direct the buyer to bind the card. | The following sample code shows how to process the `onEventCallback`: ```javascript function onEventCallback({ code, result }) { switch (code) { case code: 'SDK_ASSET_BINDING_SUCCESSFUL'; // Vaulting successful, free the SDK component and redirect to the vaulting result page. break; case code: 'SDK_ASSET_BINDING_FAIL'; // Vaulting failed. You can follow the vaultingResultCode error code prompt message and redirect the buyer to bind the card. break; case code: 'SDK_ASSET_BINDING_ERROR'; // Card binding is abnormal. You can wait for the notification of the card binding result or re-direct the buyer to bind the card. break; case code: 'SDK_ASSET_BINDING_CANCEL'; // Guide buyers to retry vaulting. break; default: break; } } ``` ## Step 4: Obtain vaulting result Server-side When the buyer completes the vaulting or the vaulting timeout, Antom will send the corresponding vaulting result to the merchant through the server-side interaction, you can obtain the payment result by one of the following methods: - Receive the asynchronous notification - Inquire about the result ### **Receive the asynchronous notification** Merchants need to implement a server-side [**notifyVaulting**](https://docs.antom.com/ac/ams/notify_vaulting.md) API; when the vaulting is completed, or vaulting failure, Antom will send asynchronous notification through this URL. The following code shows a sample of the notification request: ```json { "result": { "resultStatus": "S", "resultCode": "SUCCESS", "resultMsg": "success" }, "acquirerInfo": { "acquirerName": "ADYEN", "acquirerTransactionId": "******", "referenceRequestId": "********" }, "paymentMethodDetail": { "card": { "avsResultRaw": "4", "billingAddress": { "address1": "address1", "address2": "address2", "city": "Madrid", "region": "ES", "state": "Madrid", "zipCode": "280**" }, "brand": "VISA", "cardToken": "******", "cvvResultRaw": "1", "expiredMonth": "02", "expiredYear": "27", "funding": "DEBIT", "issuingCountry": "BR", "lastFour": "0000", "bin": "409280", "issuerName": "BANCO ITAUCARD, S.A." }, "paymentMethodType": "CARD" }, "vaultingCreateTime": "2023-10-16T01:07:22-07:00", "vaultingRequestId": "requestId1697443641665" } ``` How to verify the signature of the notification and make a response to the notification, see [Sign a request and verify the signature](https://docs.antom.com/ac/ams/digital_signature.md). > **Common questions** > > **Q: When will the notification be sent?** > > A: It depends on whether the vaulting is completed: > > - If the vaulting is successfully completed, Antom will usually send you an asynchronous notification within 3 to 5 seconds. For some payment methods like cash payment, the notification might take a bit longer. > > **Q: Will the asynchronous notification be re-sent?** > > A: Yes, the asynchronous notification will be re-sent automatically within 24 hours for the following cases: > > - If you didn't receive the asynchronous notification due to network reasons. > - If you receive an asynchronous notification from Antom, but you didn't make a response to the notification in the [Sample code](https://docs.antom.com/ac/cpnew/nf.md) format. > > The notification can be resent up to 8 times or until a correct response is received to terminate delivery. The sending intervals are as follows: 0 minutes, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, and 15 hours. > > **Q: When responding to asynchronous notification, do I need to add a digital signature?** > > A: If you receive an asynchronous notification from Antom, you are required to return the response in the [Sample code](https://docs.antom.com/ac/cpnew/nf.md) format, but you do not need to countersign the response. > > **Q: What are the key parameters in the notification that I need to use?** > > A: Pay attention to the following key parameters: > > - _result_: the vaulting result of the order. > - _paymentMethodDetail:_ the vaulting key information such as `cardToken`. ### **Inquire about the result** The merchant can call the [**inquireVaulting**](https://docs.antom.com/ac/ams/inquire_vaulting.md) API to initiate a query on the result of an order. | **Parameter name** | **Required** | **Description** | | --- | --- | --- | | _vaultingRequestId_ | Yes | The vaulting request ID generated by the merchant. | The following sample code shows how to call the **inquireVaulting** API: ```java public static void inquireVaulting(){ AlipayVaultingQueryRequest alipayVaultingQueryRequest = new AlipayVaultingQueryRequest(); //replace with your vaultingRequestId alipayVaultingQueryRequest.setVaultingRequestId("4a17609d-1749-4f53-a2fb-8bdba8d5aad8"); AlipayVaultingQueryResponse alipayVaultingQueryResponse; try{ alipayVaultingQueryResponse = CLIENT.execute(alipayVaultingQueryRequest); }catch (AlipayApiException e){ String errorMsg = e.getMessage(); // handle error condition } } ``` The following code shows a sample of the request message: ```json { "vaultingRequestId": "4a17609d-1749-4f53-a2fb-8bdba8d5aad8" } ``` The following code shows a sample of the response message: ```json { "paymentMethodDetail": { "card": { "brand": "VISA", "cardToken": "ALIPAYRW7VmurJIvO5kUUqLgvyKDEngWza4boqyf59ha3PCgu3/gNA0VWIIdVElTdeRD98yWCloE4MwfmN48sP*****", "maskedCardNo": "************0768" }, "paymentMethodType": "CARD" }, "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" }, "vaultingRequestId": "4a17609d-1749-4f53-a2fb-8bdba8d5aad8", "vaultingStatus": "SUCCESS" } ``` > **Common questions** > > **Q: How often should I call the** **inquireVaulting** **API?** > > A: Call the [**inquireVaulting**](https://docs.antom.com/ac/ams/inquire_vaulting.md) API constantly with an interval of 2 seconds until the final vaulting result is obtained or an asynchronous vaulting result notification is received. > > **Q: What are the key parameters in the notification that I need to use?** > > A: Pay attention to these key parameters: > > - _result_: represents the result of this [**inquireVaulting**](https://docs.antom.com/ac/ams/inquire_vaulting.md) API call, the result of the order needs to be judged according to _vaultingStatus_: > > - `SUCCESS` and `FAIL` represent the final result. > - `PROCESSING` represents the processing.