Web/WAP

In this topic, you'll learn how to integrate the bank SDK into a web or WAP client so that you can render payment pages in a computer browser or a mobile browser.

Prerequisites

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

Install npm.
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

Integrate the SDK by following these steps:

Import the SDK package

Client side

You can use either of the following methods to add an 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

After you have obtained available payment methods by contacting Alipay Technical Support, you can display the payment methods in the following modes:

Single bank mode: Display the payment methods by bank.
Bank type mode: Display the payment method by bank type, such as mobile banking app, online banking, and bank transfer.
Bank country mode: Display the payment methods by bank country, such as Thailand and Indonesia.

Please refer to User experience for three types of payment method display.

Note: In the bank type mode, payment methods cannot be displayed under the mobile banking app type on web clients.

Create an SDK instance by using the AMSCashierPayment 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
- 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.
- onClose: Optional. It is a callback function triggered when the buyer closes the popup.
- onEventCallback: Optional. A callback function used to trigger callback and return event code when a specific event occurs during payment.
Instantiate the AMSCashierPayment method.

Obtain the browser language.

Javascript

Editor

Create an SDK instance:

npm

Editor

Create an SDK instance:

CDN

Editor

Send a createPaymentSession (Checkout Payment) 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 (Checkout Payment) request. Get the paymentSesssionData value from the createPaymentSession response and use it in Step 5.

Pass the following parameters in your createPaymentSession (Checkout Payment) request:

paymentRequestId: The unique ID assigned by a merchant to identify a payment request.
productCode: Represents the payment product that is being used. The value is fixed as AGREEMENT_PAYMENT .
paymentNotifyUrl: The URL that is used to receive the payment result notification.
paymentRedirectUrl: The merchant page URL that the user is redirected to after the payment is completed.
paymentAmount: The payment amount that the merchant requests to receive in the order currency.
order.orderAmount: The order amount on the merchant's part. During sales promotion, the orderAmount value may differ from the paymentAmount value.
order.orderDescription: The order description.
order.referenceOrderId: The order ID on the merchant's side. Alipay suggests using one referenceOrderId for multiple paymentRequestIds when there are multiple payment requests for a single order.
paymentMethod.paymentMethodType: Specify it as BANK.
paymentMethod.paymentMethodMetaData：
- To display payment methods in the single bank mode, specify bankName as a bank name.
- To display payment methods in the bank type mode, specify paymentMethodCaregory as a payment method type. Valid values are BANK_TRANSFER, MOBILE_BANKING_APP, and ONLINE_BANKING.
- To display payment methods in the bank country mode, specify paymentMethodRegion as a country. Valid values are TH and ID.

Single bank mode

JSON

Editor

Bank type mode

JSON

Editor

Bank country mode

JSON

Editor

Render the payment pages

Client side

Use the createComponent method in the configuration object:

Create a configuration object by using the sessionData parameter: Pass the paymentSessionData value obtained in Step 4 to the sessionData 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 object 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 a payment result

Server side

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. You can also obtain the payment result by calling the inquiryPayment 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 AMSCashierPayment 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.