Web/WAP

In this topic, you'll learn how to integrate the SDK into a web or WAP client so that you can render cashier pages in a computer browser or a mobile browser. The integration process is the same for the seamless experience and the redirection experience.

Prerequisites

Before integrating the SDK, ensure that you have completed the following tasks:

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

Unlimited

Firefox

Last 2 versions

Chrome

Last 2 versions

Safari

Last 2 versions

Opera

Last 2 versions

Electron

Last 2 versions

Key Integration steps

For first-time payments and subsequent payments, integrate the SDK by following these steps:

Import the SDK package

Client side

You can use either of the following methods to add the SDK package:

Use npm: Input the install command in the command line interface.
Use CDN resources: Use the script tag in a HTML file.

Add the SDK package by using npm.

Shell

Editor

Add the SDK package by using CDN resources.

HTML

Editor

Display available payment methods

Client side

Use the tool to obtain available payment methods, customize their logos, and display them on your cashier pages.

For first-time payments, we recommend you display the names and logos of available payment methods. For subsequent payments, we recommend you display the names and logos of these payment methods as well as the desensitized buyer account.

Create an SDK instance by using the AMSEasyPay method:

Client side

Create a config object: Required. The object must contain all of the following configuration parameters:
- locale: An optional string, which is used by the merchant client to identify the language of the buyer's browser. Specify this parameter to ensure that the SDK displays pages in the correct language. The valid values are as follows. If any other values are passed, English will be used as the default language.
  - en_US: English
  - in_ID: Indonesian
  - th_TH: Thai
  - ms_MY: Malaysian
  - tl_PH: Filipino
  - ko_KR: Korean
  - vi_VN: Vietnamese
  - zh_HK: Traditional Chinese (Hong Kong, China)
- environment: A required string, which is used to specify the environment information. Valid values are:
  - sandbox: sandbox environment
  - prod: production environment
- analytics: An optional object, which is used to configure and analyze data. It contains the value:
  - enabled: An 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 log and API exceptions during the execution of the SDK.
- onEventCallback: Optional. A callback function used to trigger callback and return event code when a specific event occurs during payment.
Instantiate the AMSEasyPay method.

Obtain the browser language.

Javascript

Editor

Create an SDK instance (using npm):

JavaScript

Editor

Create an SDK instance (using CDN resources):

Javascript

Editor

Send a createPaymentSession request to the Alipay server.

Server side

After the user selects the payment method and your client detects the payment button click event, your server sends a createPaymentSession request. Get the paymentSesssionData value from the createPaymentSession response and use it in Step 5.

For the first-time payment or subsequent payments, you need to specify different parameters when calling the createPaymentSession API:

The first-time payment

paymentRedirectUrl: The URL of the merchant result page. We recommend that you pass in a mobile website URL.
authState: The unique ID generated by the merchant to initiate an EasySafePay authorization. Specify this parameter to obtain an access token for future password-free payments.
paymentNotifyUrl: The URL that is used to receive the payment result notification. It must be an HTTPS URL.
paymentSessionExpiryTime: The date and time when the payment session expires. It defaults to 1 hour and must not exceed 1 hour. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
userLoginId: The login ID that the user used to register in the wallet. The login ID can be the user's email address or phone number.
order.buyer.referenceBuyerId/buyerPhoneNo/buyerEmail: Pass in the buyer information for Alipay to provide risk control policies. Pass in one of the three parameters: referenceBuyerId, buyerPhoneNo, and buyerEmail.

The subsequent payments

paymentMethod.paymentMethodId: Pass in accessToken that you obtain from the notifyAuthorization API for the first-time payment.
paymentRedirectUrl: The URL of the merchant result page. We recommend that you pass in a mobile website URL.
paymentNotifyUrl: The URL that is used to receive the payment result notification. It must be an HTTPS URL.
paymentSessionExpiryTime: The date and time when the payment session expires. It defaults to 1 hour and must not exceed 1 hour. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
order.buyer.referenceBuyerId/buyerPhoneNo/buyerEmail: Pass in the buyer information for Alipay to provide risk control policies. Pass in one of the three parameters: referenceBuyerId, buyerPhoneNo, and buyerEmail.

First-time payment

JSON

Editor

Subsequent payment

JSON

Editor

Render the payment pages

Client side

Use the createComponent method in the configuration object:

Create a configuration object by using the paymentSessionData parameter: Pass the paymentSessionData value obtained in Step 4 to the paymentSessionData parameter of the createComponent method.
Call the createComponent method in the instantiated object. The return value is Promise, and the content is the instantiated object obtained using this method. The DOM node in the payment component can render the payment methods according to the environmental parameters and display them on the current page. You can configure the following parameter:
- appearance: An optional object, which is used to style your web page. The valid value is:
  - showLoading: An optional Boolean. It defaults to true, which indicates that you use the default loading pattern. If you do not use the default loading pattern, specify it as false.

Call the unmount() method to free SDK component resources in the following situations:

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.

Call the createComponent method:

JavaScript

Editor

Obtain an authorization result or a payment result

Server side

Regardless of a seamless experience or a redirection experience, you can obtain an authorization result and a payment result for first-time payments, and a payment result only for subsequent payments:

Obtain an authorization result
When the authorization is successful, Alipay sends you the asynchronous notification through the notifyAuthorization notification. When you receive the notification, you must return a response as instructed in Requirements. Meanwhile, you must update the authorization status of the buyer in your system and display the buyer's desensitized account obtained from the notification on your authorization management page.
Obtain a payment result
When the payment reaches a final status of success or failure, Alipay sends an asynchronous notification through the notifyPayment API to paymentNotifyUrl that you pass through the createPaymentSession API. When you receive the notification from Alipay, you must return a response as instructed in Requirements.

Note: If you call the inquiryPayment API and the cancel API after the buyer abandons the payment, you might receive a response indicating that the order does not exist, and you might not receive an asynchronous notification of the payment failure as well. We recommend that you take the following actions:

For orders that you have actively closed:

If you receive a payment success notification from Alipay, no further action is needed.
If you receive a notification from Alipay with an unknown order status, call the cancel API to cancel the corresponding order.

For duplicate payments (one merchant order corresponds to multiple Alipay orders), if you have received multiple payment success notifications for Alipay orders, keep only one Alipay order with a successful result and cancel the rest of the Alipay orders by using the cancel API.

Event codes

The SDK provides the following status codes:

SDK_START_OF_LOADING: The loading animation starts to play during the payment component creation.
SDK_END_OF_LOADING: The loading animation ends during the payment component creation.

The SDK provides the following error codes:

SDK_INTERNAL_ERROR: The internal error of the SDK occurs. Contact Alipay Technical Support to resolve the issue.
SDK_CREATEPAYMENT_PARAMETER_ERROR: The parameters passed into the AMSEasyPay method are incorrect. Ensure the parameters are passed correctly and send a new request.
SDK_INIT_PARAMETER_ERROR: The parameters passed into the createComponent method are incorrect. Ensure the parameters are passed correctly and send a new request.
SDK_CREATECOMPONENT_ERROR: An exception occurs when calling the createComponent method. Contact Alipay Technical Support to resolve the issue.
SDK_CALL_URL_ERROR: The payment method client failed to be revoked. Contact Alipay Technical Support to resolve the issue.