Android integration guide
The following sections introduce how to integrate the Alipay+ ACQP Android SDK in your project for Android devices.
Note: The payment sheet mentioned in the following sections is also known as the Alipay+ checkout page.
1. Requirements
The following requirements must be met:
- Install or update Android Studio to the latest version.
- Use target API level 15 (ICE_CREAM_SANDWICH_MR1) or higher.
- Use Gradle 4.1 or higher.
- Use AndroidX.
- Set up a physical device or use an emulator to run your app.
2. Getting started
Step 1. Add SDK to your project
- Log on to Alipay+ Developer Center to download the SDK binaries as a package. You can also obtain the source code if you need to review or customize the SDK source code.
- Add the SDK binaries to the libs folder of your project.
- Add the following code to the build.gradle file of your module.
dependencies {
// Configure the SDK aar package
compile (name: 'alipayplusclient', ext: 'aar')
// Use version 1.3.0 or later
implementation 'com.google.android.material:material:1.3.0'
}
Step 2. Set up the SDK before using other APIs
Configure the following parameters to set up the SDK before you use other APIs provided by the SDK.
IAPConfiguration configuration = new IAPConfiguration();
configuration.envType = "SANDBOX";
configuration.acquirerId = "XXX";
configuraiton.merchantId = "YYY";
configuration.language= "ZZZ";
AlipayPlusClient.setConfiguration(configuration);
3. Using SDK APIs (ACQP -> SDK)
3.1 inquirePaymentOption
The inquirePaymentOption API is used to inquire whether the Alipay+ payment method is available and if so, related data about the Alipay+ payment method, such as the Alipay+ logo, brand name, and promotion information.
You can directly render the payment method page based on the data about the Alipay+ payment method. Alternatively, you can process the data about the Alipay+ payment method and append the processing result to the data about your existing payment methods, and then render the payment method page accordingly.
Note the following things:
- If the value of the enabled parameter is
false
in the response, you can check the disableReason parameter to understand the reason for failure. Generally, you do not need to display the reason to the user. - If the value of the enabled parameter is
true
in the response, the SDK returns the logo based on the following rules:
- If no aggregated logo is preconfigured, the SDK returns the default Alipay+ logo.
- If aggregated logos are preconfigured, the SDK returns one or more aggregated logos based on the currency. If no aggregated logo matches the currency, the default aggregated logo is returned. You can use the logoPattern parameter to specify the logo that you want to use.
- To improve loading performance and reduce data transfer costs, it is recommended that you cache the image of the Alipay+ logo by its CDN URL.
- The array of the promotion information currently contains only one element. The priority of the language that is used to display the promotion information is as follows: the language that you specified in the setConfiguration API > English.
For more information about this API, see inquirePaymentOption.
3.2 showPaymentSheet
The showPaymentSheet API is used to show the payment sheet for the user to complete the payment after the user places an order with Alipay+. You can display the recommended Mobile Payment Providers (MPP)s that are supported by Alipay+ on the payment sheet. After the user selects an MPP and clicks Pay Now, the user is redirected to the MPP client to complete the payment. In the preceding process, you can receive callbacks about key events, such as when the user clicks Close or when the user clicks Pay Now.
How to handle the key events:
- When you receive the event that the user has selected an MPP and clicked Pay Now, the SDK closes the payment sheet and redirects the user to the MPP client to complete the payment. The payment status will not be updated through callbacks. Therefore, you may need to call your server to query the payment status.
- When the user clicks Close, the SDK closes the payment sheet. You can define custom logic to process the event.
- If the value of the paymentData parameter is illegal, the payment sheet is not displayed and the corresponding callback is invoked to notify the caller.
About the payment sheet:
- The payment sheet is closed only when the user clicks Close or clicks Pay Now after selecting an MPP.
For more information about this API, see showPaymentSheet.
4. Using SDK SPIs (SDK -> ACQP)
The SDK provides the following services.
4.1 LogService
The LogService supports the following SPIs:
log
The log SPI is used to obtain the details of key events that occur during the interaction between the user and the SDK. The detailed information can be used for debugging or logging.
Note that the log SPI is optional.
For more information about this SPI, see log.