Android integration guide

The following sections introduce how to integrate Alipay+ client SDK in your project for Android devices.

Note:

In the following sections, the Mobile Payment Provider is also known as Payment Service Provider (PSP).

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.
• Set up a physical device or use an emulator to run your app.

2. Getting started

This section introduces how to import and initialize the Alipay+ client SDK.

Step 1. Add SDK to your app

Complete the following steps to add the Alipay+ client SDK to your app.

Add the Maven repository

Add the Maven repository in your root build.gradle file as follows:

repositories{
  maven {
    credentials {
        username 'USER_NAME'
        password 'PASSWORD'
    }
    url 'https://globaltech.alipay.com/api/v1/file/repository/REPO_NAME/'
  }
}

Replace the values of REPO_NAME, USER_NAME, and PASSWORD with the access credentials that are provided by your Solution Architect. It is recommended that you keep the username and password in the local.properties file instead of checking them into the version control system.

Add dependencies

Add the required dependencies in the app-level build.gradle file. For example, to install all Alipay+ products, you need to add the iapconnect and iapconnect-resource dependencies as below.

// in app build.gradle
// if there are some conflicts with existing sdk, please exclude them
dependencies {
    implementation 'com.iap.ac.android:iapconnect:${iapconnect}'
    implementation 'com.iap.ac.android:iapconnect-resource:${iapconnect-resource}'
}

The iapconnect-resource dependency includes resources that are used by all Alipay+ products. It is required regardless of the products that you use.

The iapconnect dependency specifies that all Alipay+ products are to be installed.

Starting from version 2.27.0 of the Alipay+ Android client SDK, multiple dependencies are fine-grained from the iapconnect dependency for different Alipay+ products. You can add these dependencies based on the Alipay+ products that you want to use. For example, if you want to install only all Alipay+ payment products, you can add the iapconnect-payment dependency; or if you want to install only the Auto Debit payment product, you can add the iapconnect-autodebit dependency.

The following table shows the dependencies that you can add for different Alipay+ payment products.

Note:

• For more information about the dependencies that the Alipay+ client SDK provides and how to choose the dependencies as you require, see Dependencies.
• Existing users can continue using the iapconnect dependency.

It is recommended that you externalize the version numbers in the root build.gradle file so that you can easily manage upgrades in the future.

The following sample code shows how to externalize the version numbers. Ensure that you replace the values of IAPCONNECT_VERSION and IAPCONNECT_RESOURCE_VERSION with the version numbers that are provided by your Solution Architect.

ext.versions = [
    'iapconnect'        	: 'IAPCONNECT_VERSION',
    'iapconnect-resource'   : 'IAPCONNECT_RESOURCE_VERSION',
]

Add additional configurations

You can add the following configurations to ensure that the generated APK can safely use the functionalities provided by the provisioned SDK.

Configure the signature version

You can configure the signature version based on your needs. For example, you can specify only signature version 1 or specify both signature versions 1 and 2.

The following sample code shows how to specify signature version 1 in your app-level build.gradle file.

android {
    signingConfigs {  
        release {
            ...
            v1SigningEnabled true
            v2SigningEnabled false
        }
    } 

    buildTypes {
        ...
        release {
            ...
            signingConfig signingConfigs.release
        }
    }
}

The following sample code shows how to specify signature versions 1 and 2 in your app-level build.gradle file.

android {
    signingConfigs {  
        release {
            ...
            v1SigningEnabled true
            v2SigningEnabled true
        }
    } 

    buildTypes {
        ...
        release {
            ...
            signingConfig signingConfigs.release
        }
    }
}

Configure resource file obfuscation rules

To prevent specific resource files from being obfuscated, you can add either ProGuard or DexGuard configuration to set resource file obfuscation rules.

To add ProGuard configuration, create a resource file named res/raw/keep.xml with the following content:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
tools:keep="@drawable/yw_1222*" />

The yw_1222 file is the security image that contains provision information for the SDK to work. This configuration is to prevent security images from being removed during the ProGuard optimization process.

To add DexGuard configuration if your application is protected by SecurityGurad, use the following configuration to prevent security images from being removed.

-keepresourcefiles lib/**/**.so
-keepresourcefiles "res/drawable/yw_1222*"

Note: If the preceding resource file obfuscation rules do not work and your Gradle plugin version is 4.2.0 or later, you need to add android.enableResourceOptimizations=false to the gradle.properties file. This prevents resource files under the res/ folder from being obfuscated.

Step 2. Register services

The following services are available for choice. Select and register the services according to your business requirements.

• Register OAuthService

OAuthService is a service implemented by Mobile Payment Provider to provide authCode to Alipay+ client SDK. Alipay+ client SDK uses the authCode to perform OAuth.

//Init this code once, usually you can put it in the android Application onCreate()

//Register an implementation, this is done by the wallet integrators, where
//OAuthServiceProvider is your implementation of OAuthService
WalletServiceManager.getInstance().registerService(OAuthServiceProvider.class);

See getAuthCode for a sample implementation.

• Register PaymentService (for Cashier Payment and Merchant-presented Mode Payment only)

PaymentService is implemented by Mobile Payment Provider to open the cashier page for payment.

//Init this code once, usually you can just put it in the android Application onCreate()

//Register an implementation, this is done by the wallet integrators, where
//PaymentServiceProvider is your implementation of PaymentService
WalletServiceManager.getInstance().registerService(PaymentServiceProvider.class);

See pay for a sample implementation.

Step 3. Initialize SDK in your app

Call the init API to initialize the dependent libraries for the Alipay+ client SDK. It is recommended that you initialize the SDK at the onCreate of the application. If the initialization fails, call the init API again, or present the error information to the user.

If the SDK failed to be initialized, the subsequent implementation might not work normally.

Parameters

Returns

N/A

Sample:

InitConfig initConfig = new InitConfig();
// for your production version, please use 'PROD'
initConfig.envType = "DEV";

IAPConnect.init(this, initConfig, new InitCallback() {
    @Override
    public void onSuccess() {
        // success
    }

    @Override
    public void onFailure(String errorCode, String errorMessage) {
        Toast.makeText(MyApplication.get(),
                       "Initialize error, errorCode: " + errorCode + ", errorMessage: " + errorMessage,
                       Toast.LENGTH_LONG).show();
        // try again for IAPConnect.init()
    }
});

3. Using SDK SPIs (SDK -> Mobile Payment Provider App)

With the following services, you can use SPIs to interact with Mobile Payment Provider app.

OAuthService

OAuthService is used in the client SDK for all products.

The following SPIs can be used:

• getAuthCode: See getAuthCode for sample implementation.
• showAuthPage: See showAuthPage for sample implementation.

PaymentService

PaymentService is used only in Cashier Payment and Merchant-presented Mode Payment.

Currently, only pay interface in this service is used. After the Mobile Payment Provider returns the payment URL to Alipay+, Alipay+ client SDK opens the payment URL by calling the pay interface of the PaymentService. Mobile Payment Provider renders the cashier page and the user confirms the payment. See pay for sample implementation.

DeepLinkService (used in Alipay+ Rewards only)

The following SPIs can be used according to different scenarios:

• open(@NonNull Uri scheme,

            @Nullable APIContext apiContext):

This SPI is required to be implemented. See open scheme for sample implementation.

• open(@NonNull String sceneCode,

                   @NonNull Map<String, String> params,

                   @Nullable APIContext apiContext,

                   @NonNull Callback<BaseResult> openBizSceneCallback).

For scenarios where the open scheme SPI is not supported, this SPI is required to be implemented. See open sceneCode for sample implementation.

4. Using SDK APIs (Mobile Payment Provider App -> SDK)

The interfaces to be integrated vary depending on different payment products. See the following sections for details:

signContract

signContract interface is only required for Auto Debit Payment.

Before the client SDK request the authCode form Mobile Payment Provider, the user must first sign the agreement to enable the Auto Debit. Mobile Payment Provider can call signContract to request the contract content. In addition, before using this interface, Mobile Payment Provider must register an Android App Links in merchant APP, and provide the Android App Links to Alipay+. When the merchant requests to sign contract with the Mobile Payment Provider, Alipay+ provides the Android App Links to the merchant with which the user can jump to the Mobile Payment Provider App.

For sample usage, see signContract.

decode

decode interface is required for Cashier Payment and Merchant-presented Mode Payment.

Use this interface to decode the code, which might be an order code or a collection code generated by Alipay+.

When Mobile Payment Provider receives a deep link which contains alipayconnectcode, parse the query parameter in the link and obtain the code value. For example, a deep link is iaps://alipayconnect/alipayconnectcode?codeValue=https://qr.alipay.com/bax122344556789075, in which the code value is https://qr.alipay.com/bax122344556789075. Call the decode interface with the code value.

For sample usage, see decode.

clear

clear interface is required for Cashier Payment , Merchant-presented Mode Payment, and User-presented Mode Payment.

Using the functions of Alipay+ Client SDK requires the user authorization. After the user's authorization, the SDK is bound to a specific user. When a user logs out, Mobile Payment Provider must call the clear interface to clear the code information that is bound with the user and cached by the SDK.

For sample usage, see clear.

getPaymentCode

getPaymentCode interface is only required for User-presented Mode Payment.

Mobile Payment Provider uses the getPaymentCode interface to obtain the payment code from Alipay+. The payment code is returned by IPaymentCodeListener.

The following list describes when Mobile Payment Provider calls this interface:

• Call this interface when Mobile Payment Provider generates or refreshes a payment code each time. The payment code might be expired after 1 minute, so refresh the payment code within 1 minute. It's recommended to refresh the code every 30 seconds.
• Call this API to refresh the payment code when the value of region changes.

For sample usage, see getPaymentCode.

inquireQuote

inquireQuote interface is only required for User-presented Mode Payment.

Use the inquireQuote interface to query the foreign exchange rate between a pair of currency. The exchange rate returned by Alipay+ is only for reference.

For sample usage, see inquireQuote.

openACCenter

openACCenter interface is only used for openning the Alipay+ Rewards mini-program.

Use the openACCenter interface to create an Alipay+ Rewards mini-program instance and navigate to the Alipay+ Rewards mini-program.

for sample usage, see openACCenter.

Appendix: Android libraries

The following image shows all libraries included in the SDK:

See the following list for mandatory dependencies:

• alipayconnect-x.y.z.aar: provide interfaces that are related with Alipay+ business specifically.
• alipayconnect-core-x.y.z.aar: provide the core implementation of Alipay+ SDK business.
• Griver-x.y.z.aar: mini Program framework SDK.
• acresource-x.y.z.aar: resource library, which includes configurations. Do not use acresource-x.y.z-mock_wallet.aar of the demo project in your wallet directly. Use the one in the published SDK for you. Each Mobile Payment Provider wallet uses a unique resource library.
• config-x.y.z.aar: used to fetch the configurations from Alipay+ server.
• instance-info-x.y.z.aar: used to obtain device information.
• LogLite-sdk-x.y.z.aar: used to process logs.
• rpc-x.y.z-multigateway.aar: used for network implementation.
• lifecycle-process-x.y.z.aar: used by the config-x.y.z.aar library. This is a Android library which is used to perform the component life cycle management.
• multigateway-sdk-x.y.z.date.jar: used by the rpc-x.y.z-multigateway.aar library and the library is used to adapt to multiple gateways.
• acrpccommon-x.y.z.jar: basic request and response definitions for network access. Required library version is 1.2.4 or higher.
• gson: used by the rpc-x.y.z-multigateway.aar library to assemble and parse data between client and server.
• common-x.y.z-base.aar: common interface for all basic functions.

• If the iapcommon library is already integrated, integrate common-x.y.z-base.aar.
• If the iapcommon library is not integrated, integrate common-x.y.z-withRpc.aar.

See the following list for optional dependencies:

• container-x.y.z.aar: used to open H5 page when user scans the merchant QR code.

• If AppContainer is already integrated, do not integrate container-x.y.z.aar.
• If AppContainer is not integrated, integrate container-x.y.z.aar.

• common-log: a temporary library, which isn't included in the official released version.

• If the iapcommon library is already integrated, do not integrate common-log.
• If the iapcommon library is not integrated, integrate common-log.

• SecurityGuardSDK-external-release-5.4.12158568.aar: used to encrypt, decrypt and generate the signature for HTTP.

• If SecurityGuardSDK is already integrated, do not integrate SecurityGuardSDK-external-release-5.4.12158568.aar.
• If SecurityGuardSDK is not integrated, integrate SecurityGuardSDK-external-release-5.4.12158568.aar.

Note:

x.y.z in the preceding instruction is the placeholder and represents the library version.