Android

In this topic, you'll learn how to integrate the card payment SDK into an Android client so that you can render cashier pages in a mobile application.

Prerequisites

Before integrating the card payment SDK, familiarize yourself with the Integration guide and Overview. This will enable you to understand the steps for integrating server APIs and notes for calling the APIs. Also, ensure that you have completed the following tasks:

Obtain a client ID in Alipay Developer Center.
Properly configure keys in Alipay Developer Center.
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

Integrate the card payment 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 to the build.gradle file.

Add dependencies to the build.gradle file.

build.gradle

Editor

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("es", "ES"): Spanish
  - locale("ko", "KR"): Korean
  - locale("pt", "BR"): Portuguese
  - locale("en", "US"): English
- 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 API, which is used for event handling in the subsequent process. The API 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 API in that of the configuration object to execute event callbacks.
Instantiate the AMSComponentCheckout method.

Create an SDK instance:

Java

Editor

Send a createPaymentSession (Cashier Payment) request to the Alipay server.

Merchant client

After the buyer selects a card payment method for payment, your client starts monitoring the payment button click event. When your client detects that the payment button is clicked, your server needs to send a createpaymentSession (Cashier Payment) request to the Alipay server. After you receive the response from the API call, use the value of the paymentSessionData parameter to complete Step 4.

Note: In your createPaymentSession (Cashier Payment) request, specify paymentRedirectUrl as the URL Scheme that you provide to redirect buyers to the payment result page upon payment completion.

The following sample for calling the createPaymentSession API includes mandatory parameters and several optional parameters.

JSON

Editor

The response sample of the API call is shown as follows:

JSON

Editor

Create a component for collecting payment factors by using the createComponent method in the instantiated object

Merchant client

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.
paymentType: A required string. The fixed value is CARD.
paymentSessionData: A required string. Pass the complete data in the paymentSessionData parameter obtained in the response through the createpaymentSession (Cashier Payment) API to the paymentSessionData parameter.
appearance: A required parameter belonging to the AMSPaymentAppearance type. This parameter is used for extensions. A valid value is null.

Create a configuration object:

JavaScript

Editor

Reference

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 createComponent method are incorrect. Ensure the parameters are passed correctly and send a new request.
SDK_CALL_URL_ERROR: Represents one of the following cases:
- The redirection to the merchant page failed to be executed.
- The parameter paymentRedirectUrl in your createpaymentSession (Cashier Payment) request is not passed or passed incorrectly.
SDK_INTEGRATION_ERROR: Dependencies are not found. Ensure that the dependencies are added correctly and retry the integration process.

Code sample in key steps

The following code sample shows the key steps during integration. The sample does not include the code used for calling the createpaymentSession (Cashier Payment) API.

Java

Editor