Android

In this topic, you'll learn how to integrate the SDK into an Android client so that you can render cashier pages in a mobile application. 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:

Install the latest version of Android Studio.
Target at least Android 4.4 (API level 19) or higher.
Use Gradle 4.1 or earlier.
Configure a physical machine or simulator to run your application.

Key integration steps

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

Integrate the SDK package

Client side

To integrate the SDK package, please refer to Integrate the SDK Package.

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:

Client side

Follow these steps to create an SDK instance:

Create a configuration object: A required object. The object must contain all of the following configuration parameters:
- setLocale: 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.
  - locale("en", "US"): English
  - locale("in", "ID"): Indonesian
  - locale("th", "TH"): Thai
  - locale("ms", "MY"): Malaysian
  - locale("tl", "PH"): Filipino
  - locale("ko", "KR"): Korean
  - locale("vi", "VN"): Vietnamese
  - locale("zh", "HK"): Traditional Chinese (Hong Kong, China)
- setOption: Optional. It is used to specify whether to use the default loading pattern and the sandbox environment. Valid values are:
  - "sandbox", "true": Sandbox environment
  - "sandbox", "false": Production environment
  - "showLoading", "true": Use the default loading pattern.
  - "showLoading", "false": Do not use the default loading pattern.
  - "windowGravity","LANDSCAPE_CENTER": Center the window in landscape mode.
  - "windowGravity","LANDSCAPE_RIGHT": Align the window to the right in landscape mode.
Create an instance of the onCheckoutListener interface, which is used for event handling in the subsequent process. The interface includes the following method:
- onEventCallback: Required. A callback function that monitors payment events on the checkout page, returning eventCode and eventResult.
Set the instance of the onCheckoutListener interface in that of the configuration object to execute event callbacks.
Instantiate the AMSEasyPay method.

Note: To improve component performance and user experience, you can pre-create a component instance before calling the createPaymentSession API.

Create an instance:

Java

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 scheme URL or H5-scheme 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 scheme URL or H5-scheme 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

The AMSEasyPay component cannot be reused. Create a new AMSEasyPay component before each createPaymentSession API request.

Call the createComponent() method in the configuration object and pass in the following parameters:

activity: A required object belonging to the Activity type. It is used to include the information about context parameters on the current page.
sessionData: A required string. Pass the paymentSessionData value obtained in Step 4 to the sessionData parameter of the createComponent method

Call the onDestroy() 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.

Re-create AMSEasyPay:

Java

Editor

Call the createComponent method:

Java

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.
SDK_PAYMENT_CANCEL: The user cancels the payment on the account confirmation page or the large transaction confirmation page.

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_CALL_URL_ERROR: The payment method client failed to be revoked. Contact Alipay Technical Support to resolve the issue.
SDK_INTEGRATION_ERROR: Dependencies are not found. Ensure that the dependencies are added correctly and retry the integration process.

Integration key steps code sample

The following code sample shows the key steps during integration.

Java

Editor