Web/WAP
In this topic, you will learn how to integrate the APM SDK into a web or WAP client, allowing you to render cashier pages in computer and mobile browsers.
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:
Integrate the SDK by following these steps:
Integrate the SDK package
To integrate the SDK package, please refer to Integrate the SDK Package for Web/WAP.
Create the SDK instance by using the AMSCashierPayment
- 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. 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
: Englishpt_BR
: Portugueseko_KR
: Koreanes_ES
: Spanishfr_FR
: Frenchnl_NL
: Dutchit_IT
: Italiande_DE
: Germanzh_CN
: Simplified Chinesezh_HK
: Traditional Chinesems_MY
: Malayvi_VN
: Vietnamesein_ID
: Indonesianth_TH
: Thai
- environment: Required string. It is used to pass in environmental information. Valid values are:
sandbox
: Sandbox environmentprod
: Production environment
- analytics: Optional object. 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 asfalse
.
- enabled: Optional Boolean. It defaults to
onLog
: Optional. It is a callback method that is used to generate the error information about logs and API exceptions during the execution of the SDK.onError:
Optional. Triggered when an error occurs during SDK usage (initialization exception, network timeout, etc.). Refer to the References for more details.onEventCallback
: Required. A callback function that returns a specific event code when a payment event occurs during the runtime of the SDK, such as payment result, payment cancellation. Refer to the References for more details.
- locale: Optional. String type. 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:
- Instantiate
AMSCashierPayment
.
Note: The environment set by environment should be consistent with the environment in which you call the createPaymentSession API in step 3.
Initiate a createPaymentSession request
The merchant client monitors the click events of the Payment button itself. When the buyer selects the card payment method and clicks the Payment button, the merchant client initiates createPaymentSession request to the APO server. Once the response to the createPaymentSession request is received, the paymentSessionData value in the response is used in Step 4.
Create a payment component using the createComponent
method in the instance object
- Create a configuration object using the sessionData parameter: Pass in the complete data of the paymentSessionData field obtained in the response of the createPaymentSession request into the sessionData parameter.
- Call the
createComponent()
method in the instance object, returning aPromise
with the component instance object obtained using this method. The payment block DOM node can render a pop-up view on the current page based on parameters.- appearance: Optional. Object type for customized appearance theme configuration, and it 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 asfalse
.
- showLoading: Optional. Boolean type. The default value is
- appearance: Optional. Object type for customized appearance theme configuration, and it contains the following parameters:
-
Free resources of the SDK component by calling the
unmount()
method in the instance object. You need to unmount a component in the following cases:- When the user exits the checkout page, free the component resources created in the createPaymentSession.
- When the user initiates multiple payments, free the component resources created in the previous createPaymentSession.
Display payment events and payment results
Payment events:
Implement the onEventCallback function to listen for payment events. Pay attention to the following event codes for further actions:
- When showLoading in step 4 is
false
, you receive the following event codes:SDK_START_OF_LOADING
: display a custom loading animation.SDK_END_OF_LOADING
: end the custom loading animation.
- When a user exits the payment page without submitting an order, you receive the following event code:
SDK_PAYMENT_CANCEL
: Guide the user to retry the payment.
Payment results:
- Redirect payment: After the payment flow completes, users are redirected to the provided callback URL. Guide users through the next steps on the redirected page.
- Non-redirect payment: The non-redirect payment return event codes related to the payment results. Handle different payment results based on the following event codes:
SDK_PAYMENT_SUCCESSFUL
: Payment was successful. Suggest redirecting users to the payment result page.SDK_PAYMENT_FAIL
: Payment failed. We suggest that you check the value of paymentResultCode in theonEventCallback
result data for details. Guide users to retry the payment based on the provided information.SDK_PAYMENT_ERROR
: The payment status was abnormal. We suggest that you check the value of paymentResultCode in theonEventCallback
result data for details. Guide users to retry the payment based on the provided information.SDK_PAYMENT_PROCESSING
: Payment was being processed. We suggest that you check the value of paymentResultCode in theonEventCallback
result data for details. Guide users to retry the payment based on the provided information.
Note: The payment results displayed on the frontend are for informational purposes only. Verify the final order status on the server-side.
The References offer callback event codes and integration key step code examples. For further details, refer to the References.