Android

In this topic, you'll learn how to integrate the pop-up card vaulting SDK with an Android client. This will allow you to render the card vaulting page in a mobile application.

Prerequisites

Before the integration, ensure that you have completed the following tasks:

Install the latest version of Android Studio.
Use target API level 19 or later.
Use Gradle 4.1 or later.
Configure a physical machine or emulator to run your application.

Key integration steps

Integrate the independent card vaulting SDK by following these steps:

Integrate the SDK package

Merchant client

To integrate the SDK package, please refer to Integrate the SDK Package for Android.

Create an SDK instance using AMSVaulting.

Merchant client

The process of creating an SDK instance includes the following steps:

Create a configuration object: Required. Object type, which includes the following parameters:
- setLocale: Optional. String type. It is used by the merchant client to identify the browser language and pass in the language information. The SDK uses the information to render the cashier page in the corresponding language. Valid values are listed as follows. If other values are passed, English is used by default:
  - "en", "US": English
  - "pt", "BR": Portuguese
  - "ko", "KR": Korean
  - "es", "ES": Spanish
  - "fr", "FR": French
  - "nl", "NL": Dutch
  - "it", "IT": Italian
  - "de", "DE": German
  - "zh", "CN": Simplified Chinese
  - "zh", "HK": Traditional Chinese
- setOption: Optional. Used to specify whether to use the sandbox environment. Valid values are:
  - "sandbox", "true": Sandbox environment.
  - "sandbox", "false": Production Environment.
  - "notRedirectAfterComplete", "true": The default value is false, indicates that redirection to your page takes place after the card vaulting is complete. The same applies when the value is empty. When the value is true, redirection will not take place after the card vaulting is complete. You need to use the customer event code to control the card vaulting and complete the subsequent process. Please note that the card vaulting result event code returned by the client is only used as a reference for the redirection of the client page. For transaction status updates, please refer to the results returned by notifyVaulting or inquireVaulting.
Create an instance of the OnCheckoutListener API to handle corresponding events that occur in the subsequent process. It contains the following function:
- OnEventCallback: Required. The card vaulting event callback function that returns eventCode and eventResult.
Set the instance of the onCheckoutListener API to the configuration instance for executing event callbacks.
Instantiate AMSVaulting.

Sample code of creating the SDK instance

Java

Editor

Initiate a createVaultingSession request

Merchant server

The merchant client monitors the click events of the Add Card button itself. When the buyer selects a payment method and clicks the card vaulting button, the merchant server sends the createVaultingSession request to the Antom server. Once the response to the createVaultingSession request is received, the vaultingSessionData value in the response is used in step 4.

If you need to automatically redirect buyers to your page after card vaulting is complete, pass in the redirectUrl field in the createVaultingSession API. If you want to control the subsequent process of card vaulting through client-side event codes, you do not need to pass in the redirectUrl field. You can monitor the card vaulting result event code through onEventCallback.

Note: The vaulting result event code returned by the client is only used as a reference for redirection operations on the client page. Please refer to the notifyVaulting API on the server for updates on the vaulting status.

Sample code of the createVaultingSession request

Editor

Use createComponent in the instance object to create the card vaulting element collection component:

Merchant client

Call the createComponent() method and pass in the following parameters:
- activity: Required. Activity type object, used to contain contextual parameter information for the current page.
- sessionData: Required. String type. Pass in the complete data of the vaultingSessionData field obtained from the response of the createVaultingSession request into the sessionData parameter.
Free resources of the SDK component by calling the onDestroy() method in the instance object. You need to unmount the component in the following cases:
- When the buyer exits the card vaulting page, free the component resources created in createVaultingSession.
- When the buyer initiates card vaulting multiple times, free the component resources previously created in createVaultingSession.

Sample code of calling createComponent()

Java

Editor

Sample code of key integration steps

The following sample code demonstrates the key steps in the integration process. The code does not include examples of calling the createVaultingSession API. You need to handle the server API calls on your own.

Java

Editor

Event codes

The SDK may return the following error codes:

SDK_INTERNAL_ERROR: SDK internal error. Please contact Antom technical support.
SDK_CREATEPAYMENT_PARAMETER_ERROR: The createComponent method passed in parameters abnormally, please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_INIT_PARAMETER_ERROR: The AMSVaulting method passed in parameters abnormally. Please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_CREATECOMPONENT_ERROR: Component initialization exception. Please contact Antom technical support.
SDK_ABNORMAL_RENDERING_DATA: Rendering data exception. Please retry the initialization process or contact technical support for troubleshooting.
SDK_SUBMIT_NETWORK_ERROR: Interface call failed due to network reasons. It may occur in the submit method submission. Please try to submit it again.

The SDK may return the following status codes:

SDK_CALL_URL_ERROR: Fail to redirect to the merchant page. Check if the redirect merchant link can be accessed normally. If the URL can be accessed normally, please contact Antom technical support.
SDK_CALL_URL_SUCCESS: Redirection to the merchant page is successful. No further action is required.
SDK_FORM_VERIFICATION_FAILED: The form validation fails after submitting the form. The SDK will display the form error on the element collection page. The merchant can prompt the buyer to enter the correct information.
SDK_DUPLICATE_SUBMISSION_BEHAVIOR: The form is submitted repeatedly. The merchant can prompt the buyer not to click submit repeatedly.

The SDK may return the following card-vaulting result event codes:

SDK_ASSET_BINDING_FAIL: Card vaulting failed. We suggest that you follow the vaultingResultCode error code prompt and guide the buyer to retry the card vaulting.
SDK_ASSET_BINDING_SUCCESSFUL: Card vaulting is successful, and the SDK needs to be revoked. It is recommended that you redirect to the vaulting result page.
SDK_ASSET_BINDING_ERROR: Card vaulting is abnormal. We suggest that you wait for the card vaulting result notification or redirect the buyer to retry card vaulting.

The SDK may return the following card vaulting status (vaultingStatus):

SUCCESS: Indicates successful card vaulting.
FAIL: Indicates card vaulting failed.

The SDK may return the following result codes (result.resultCode):

Code	Value	Message	Further actions
SUCCESS	S	Success	No further action is required.
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.	Wait for the card vaulting notifications or inquire about the card vaulting results.

The SDK may return the following card vaulting result codes (vaultingResultcode):

Code	Value	Message	Further actions
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.

Sample code of card vaulting result codes handling:

Java

Editor

Sample code of card vaulting result:

Successful

Failed

Editor