Android

In this topic, you'll learn how to integrate the independent card binding SDK into an Android client. This will allow you to render cashier pages in a mobile application.

Prerequisites

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

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

Key integration steps

Integrate the independent card binding SDK by following these steps:

Import the SDK package

Merchant client

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

Add dependencies to the build.gradle file.

Groovy

Editor

Create an SDK instance by using the AMSVaulting:

Merchant client

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

Create a config object: Required. The object must contain all of the following configuration parameters:
- setLocale: Optional. String type. It is used to pass in language information. Valid values are listed as follows. 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
- setOption: Optional, used to set whether to adopt the default loading style and whether to use a sandbox environment. Supported values include：
  - "sandbox", "true": Sandbox environment.
  - "sandbox", "false": Production Environment.
  - "showLoading", "true": Use the default loading style.
  - "showLoading", "false": Do not use the default loading style.
  - "showSubmitButton", "true": Configure the SDK component to render the binding card button.
  - "showSubmitButton", "false": Configure the merchant to render the card binding button, while also calling the submit method in the instance object to trigger the submission card binding process.
Create an instance of the onCheckoutListener API for handling corresponding events in subsequent processes, including the following methods：
- onEventCallback: Required. Cashier payment event callback method, returning eventCode and eventResult.
Set the instance of the onCheckoutListener API to the configuration instance for executing event callbacks.
Instantiate AMSVaulting.

Create an 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 the payment method and clicks the card binding button, the merchant client initiates 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 asset binding is complete, upload in the redirectUrl field in the createVaultingSession API. If you want to control the subsequent process of card binding completion yourself through client-side event codes, you do not need to upload this field, and can monitor the card binding result event code through onEventCallback.

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

JSON

Editor

Render card binding element collection components

Merchant client

Use theMountComponent method in the instance object:
- activity: Required. Activity type object, used to contain contextual parameter information for the current page.
- appearance is AMSPaymentAppearance type.
  - "showSubmitButton", "true": Configure the SDK component to render the card binding button
  - "showSubmitButton", "false": Configure the merchant to render the card binding button, while also calling the submit() method in the instance object to trigger the submission of the card binding process.
- sessionData: Required. String type. Pass the complete data of the vaultingSessionData field obtained from the response of the asset binding session creation request into the vaultingSessionData parameter of MountComponent.
- parentViewGroup: Required, FrameLayout type, used to bind the view to the merchant's page layout. The layout parameter needs to be set to wrap_content. The SDK will automatically adjust the view width and height according to the size of the internal content of the view.
Call the submit() method in the instance object:
- Calling this method can trigger the card binding submission process, with a return value of Promise and a specific event code. These event codes will also be returned through events such as onError or onEventCallback.
- If you need to pass in pre-collected billing address information for AVS verification, you can configure the following parameters to be passed in through the submit method.
  - billingAddress: Optional, Object type. Billing address information is used to identify the payer's identity and location. It contains the following parameters:
    - region: Required. String (2). ISO 3166 compliant 2-digit country code.
    - state: Optional. String (8). The name of the state, country, or province.
    - city: Optional. String (32). Name of the city, region, suburb, town or village.
    - address1: Optional. String (256). Address line 1, e.g., street address, P.O. Box, and company name.
    - address2: Optional. String (256). Address line 2, e.g., apartment, suite, unit, and building information.
    - zipCode: Optional. String (32). Zip code.

Call mountComponent()

JavaScript

Editor

Uninstall components

Merchant client

Destroy a created component by calling the onDestroy() method in the instance object. You need to unmount a component in the following cases:

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.

Note: Only one component can be created at a time. If you need to use a different vaultingSessionData or recreate a component, you need to first execute the uninstall method.

Call onDestroy()

Javascript

Editor

Obtain the result

Merchant server

When the card is successfully bound, Antom sends an asynchronous notification via notifyVaulting API to the notification recipient address that you passed in the notifyVaulting API. If you receive an asynchronous notification from Antom, you need to return the response in the sample code format of Process the notification. At the same time, you need to update the card binding status of the buyer in your system, and it is recommended to display the corresponding desensitized card number on your card binding management page according to the card information in the notification.

Event codes

The SDK provides the following error codes:

SDK_INTERNAL_ERROR: SDK internal error. Please contact Ant Group technical support.
SDK_CREATEPAYMENT_PARAMETER_ERROR: mountComponent method passed in parameter abnormally, please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_INIT_PARAMETER_ERROR: AMSVaulting method passed in parameter abnormally. Please check if the parameter is correct and retry the request with a different vaultingRequestId.
SDK_CREATECOMPONENT_ERROR: Component initialization exception. Please contact Ant Group 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 submit method submission. Please try to submit it again.

The SDK provides the following status codes:

SDK_START_OF_LOADING: The loading animation starts to be shown when the component is created. When configured to hide loading and use a custom animation, the custom animation can be rendered at this time.
SDK_END_OF_LOADING: The loading animation ends when the component is created. When configured to hide loading and use custom animation, the animation can be hidden at this time.
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 Ant Group technical support.
SDK_CALL_URL_SUCCESS: The merchant page was 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 also guide the user to enter the correct information through the text.
SDK_DUPLICATE_SUBMISSION_BEHAVIOR: The form is submitted repeatedly. The merchant can prompt the user with a toast so that they don't have to click submit repeatedly.

The card-binding result event codes and result codes provided by the SDK are as follows:

Result event codes (code):

SDK_ASSET_BINDING_FAIL: Card binding failed. We suggest that you follow the vaultingResultCode error code prompt and guide the user to bind the card again.
SDK_ASSET_BINDING_SUCCESSFUL: Card binding is successful, and the SDK needs to be deregistered. Suggest redirecting to the binding result page.
SDK_ASSET_BINDING_ERROR: Card binding is abnormal. We suggest that you wait for the card binding result notification or redirect the user to bind the card.

Inquire about the card binding status on the server side (vaultingStatus):

SUCCESS: Indicates card binding was successful.
FAIL: Indicates card binding failed.

Inquire about the result code on the server side (result.resultCode):

Result code	Value	Message	Suggestion
SUCCESS	S	Success	-
PROCESS_FAIL	F	A general business failure occurred.	It requires manual confirmation of the issue. We suggest that you contact Antom technical support to resolve the issue.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	-

Inquire about the card binding result code on the server side (vaultingResultcode):

Result code	Value	Message	Suggestion
PROCESS_FAIL	F	A general business failure occurred.	It requires manual confirmation of the issue. We suggest that you contact Antom technical support to resolve the issue.

Example of card binding result event code processing:

Java

Editor

Example of card binding result:

Successful

Failed

Editor