Web/WAP
In this topic, you'll learn how to integrate the pop-up payment experience SDK into a web or WAP client. This will help you render cashier pages both in a computer and mobile browser.
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. If other values are passed, English is used by default:
en_US
: Englishes_ES
: Spanishfr_FR
: Frenchnl_NL
: Dutchit_IT
: Italiande_DE
: Germanzh_CN
: Simplified Chinese
- 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.onEventCallback
: Optional. A callback function that returns various types of data or values, including event codes, cardPaymentResultInfo parameter for card payment, and popRiskDecisionResultInfo parameter for risk control. See the References for further information.onError
: Optional. Triggered when an error occurs during SDK usage (initialization exception, network timeout, etc.). Refer to the error codes in the References.
- 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:
- 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.
For card token payment mode with bound cards, you need to pass in the paymentMethod.paymentMethodId field to the card token returned to you by APO after the buyer binds the card. The way to obtain the card token is as follows:
- Independent card binding: Obtain the card token through the card.cardToken field in the asset binding result notification sent to you by APO.
- Non-independent card binding: Obtain the card token through the paymentResultInfo.cardToken field in the payment result notification sent to you by APO or the response to actively query the payment result.
Create a payment element collection 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
- notRedirectAfterComplete: Optional, Boolean type. The default value is
false
, which means it will jump back to your page after the payment is completed. The same applies when the value is empty.true
value means there will be no jump after the payment is completed. You need to use the customer event code to control the card binding to complete the subsequent process. Please note that the payment result event code returned by the client is only used as a reference for the jump operation of the client page. For transaction status's updates, please refer to the results returned by the server's notifyPayment or inquiryPayment API.
- 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 switches views to exit 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.
- When the user completes the payment and sets notRedirectAfterComplete to
true
, free the component resources after obtaining specific payment result codes.
The References offers callback data and code samples for integration steps. For further details, refer to the References.