Web/WAP

In this topic, you'll learn how to integrate the independent card binding SDK into a web or WAP client. This will allow you to render cashier pages in both computer and mobile browsers.

Prerequisites

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

Install npm (Node Package Manager).
Properly handle compatibility issues: Provide corresponding polyfills for Internet Explorer and other old browser versions. We recommend that you use 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:

Edge

Lastest 2 versions

Firefox

Lastest 2 versions

Chrome

Lastest 2 versions

Safari

Lastest 2 versions

Opera

Lastest 2 versions

Electron

Last 2 versions

Key integration steps

Integrate the independent card binding SDK by following these steps:

Integrate the SDK package

Merchant client

To integrate the SDK package, please refer to Integrate the SDK Package for Web/WAP.

Create an SDK instance by using AMSVaulting

Merchant client

Create a config object: Required. The object must contain all of the following configuration parameters:
- locale: 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
- environment: Required string. It is used to pass in environmental information. Valid values are:
  - sandbox: Sandbox environment
  - prod: Production environment
- analytics: Optional object. It is used to configure and analyze data. It contains the following value:
  - 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: Optional. It is a callback function that is used to generate the error information about logs and API exceptions during the execution of the SDK.
- onEventCallback: Optional. A callback function that returns a specific event code when a payment event occurs during the runtime of the SDK. Examples of events include 3D Secure authentication, payment failure, or redirection failure. Refer to SDK event code for more details.
- onError: Optional. Triggered when an error occurs during SDK usage (initialization exception, network timeout, etc.).
Instantiate AMSVaulting.

Obtain the browser language

JavaScript

Editor

Create the SDK instance using the npm import package method and CDN import package method

npm

CDN

Editor

Initiate an asset binding session creation 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 a 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, pass 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 pass 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. Please refer to the notifyVaulting API on the server for updates on the binding status.

JavaScript

Editor

Render card binding element collection components

Merchant client

Use the MountComponent()method in the instance object:
- Create a configuration object using the sessionData parameter: Pass the full data of the vaultingSessionData field obtained in Step 4 into the sessionData parameter of mountComponent.
- Call the mountComponent() method in the instance object, returning a Promise with the component instance object obtained using this function. The Payment Block DOM node renders the Binding Elements collection view based on the environment parameters and inserts it into the current page. You can configure the following parameters:
  - appearance: Optional. Object type for customized appearance theme configuration, and contains the following parameters:
    - showLoading: Optional. Boolean type. The default value is true, which shows the default loading animation. If you don't use the default loading animation, you need to specify this value as false.
    - showSubmitButton: Optional. Boolean type. The default value is false, which indicates whether the button is rendered by the component. If the value is false, then the submit method of the instance object should be called to trigger the submit button process.
Call the submit()method in the instance object:
- Calling this function triggers the card-binding submission process, and the return value is a Promise that returns a specific event code. These event codes are also returned by events such as onError or onEventCallback.
- If you need to pass in pre-collected billing address information for AVS validation, you can configure the following parameters to be passed in via the submit method.
  - billingAddress: Optional Object. Billing address information is used to identify and locate the payer. 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 unmount() 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 function.

Call unmount()：

JavaScript

Editor

Obtain the result

Merchant Server

When the card is successfully bound, Alipay sends an asynchronous notification via the notifyVaulting API to the notification recipient address that you passed in the notifyVaulting API. If you receive an asynchronous notification from Alipay, 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 function passed in parameter abnormally, please check if the parameter is correct and retry the request by replacing vaultingRequestId.
SDK_INIT_PARAMETER_ERROR: AMSVaulting passed in parameter abnormally. Please check if the parameter is correct and retry the request by replacing 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:

JavaScript

Editor

Example of card binding result:

Successful

Failed

Editor