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.
Use AndroidX.
Configure a physical machine or simulator to run your application.

Key integration steps

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

Import the SDK package

Merchant client

After you download the resource package in Alipay Developer Center, perform the following steps:

Move the unzipped .aar file into the libs file of your project.
Declare the reference of the .aar file in the build.gradle file in the project.
Add dependencies in the build.gradle file. To integrate fastjson, see fastjson Integration Guide.
For apps targeting Android 9 and above, to use the Apache Http client, declare the settings in the AndroidManifest.xml file in the root directory of your project and declare the use of the org.apache.http.legacy library in the gradle.build file.

Note: Apps with a SDK version of 23 or lower need the attribute android:required="false" because the org.apache.http.legacy library is not available on devices with an API level below 24. (On these devices, the Apache HTTP classes are provided in the bootclasspath.)

As an alternative to using the runtime Apache libraries, apps can bundle their own version of the org.apache.http library in their APK. To this end, repackage the library (using a utility like Jar Jar) to avoid any class compatibility issues with the classes provided at runtime.

Add dependencies in the build.gradle file

Shell

Editor

Declare the settings in the AndroidManifest.xml file

XML

Editor

Declare the use of the org.apache.http.legacy library in the gradle.build file

XML

Editor

Display available payment methods

Merchant client

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 future 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 AMSComponentCheckout()method:

Merchant client

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.
Create an instance of the onCheckoutListener interface, which is used for event handling in the subsequent process. The interface includes the following method:
- onPaymentEventCallback(): Required. It is a callback function that monitors payment events on cashier pages. It returns eventCode and message.
Set the instance of the onCheckoutListener interface in that of the configuration object to execute event callbacks.
Instantiate the AMSComponentCheckout method.

Create an SDK instance:

Java

Editor

Send a createPaymentSession request to the Alipay server.

Merchant server

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 future 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 Easy Pay 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 future 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

Future payment

JSON

Editor

Render the payment pages

Merchant client

Use the createComponent method in the configuration object.

Call the createComponent method 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.
paymentSessionData: A required string. Pass the paymentSessionData value obtained in Step 4 to the paymentSessionData parameter of the createComponent method.

Call the createComponent method:

Java

Editor

Obtain an authorization result or a payment result

Merchant server

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 future 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 AMSCheckout 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.