Airwallex Android SDK

Airwallex Android SDK is a flexible tool that enables you to integrate payment methods into your Android App. It also includes a prebuilt UI that provides you the flexibility to choose to use any part of it, while replacing the rest with your own UI.

This section will guide you through the process of integrating Airwallex Android SDK. We assume you are an Android developer and familiar with Android Studio and Gradle.

To accept online payments with Airwallex Android SDK, please complete preparation work first and choose the integration option according to your need.

Preparation

Before you start

Integration options

Airwallex Native UI integration You can choose to use this SDK with our prebuilt UI page, this is recommended usage.
Low-level API Integration You can build your own custom UI and use our low-level APIs.

Our demo application is available open source on Github and it will help you to better understand how to integrate Airwallex Android SDK in your Android App.

Overview

Airwallex API

Airwallex Android SDK is a flexible tool that enables you to integrate payment methods into your Android App.

Note: The Airwallex Android SDK is compatible with apps supporting Android API level 21 and above and SDK file size is 3188.04KB approximately

Payment methods supported:

Cards: Visa, Mastercard. If you want to integrate Airwallex API without our Native UI for card payments, then your website is required to be PCI-DSS compliant.
E-Wallets: Alipay, AlipayHK, DANA, GCash, Kakao Pay, Touch ‘n Go, WeChat Pay

Airwallex Native UI

Airwallex Native UI is a prebuilt UI which enables you to customize the UI color and fit your App theme. You can use these components separately, or pack our prebuilt UI into one flow to present your payment.

#	Native UI	Picture
1	`Edit shipping info page` This page contains a detailed shipping form for shopper to fill in, after the shopper successfully saved the form, the shipping info object will be returned
2	`Select payment method page` This page will display all the available payment methods to shopper, the shopper can choose any one of them to pay
3	`Input card information module` This module contains card number, expiration date and cvv.
4	`Confirm payment intent page` You need to pass in a PaymentIntent object and a PaymentMethod object. It will display the current selected payment amount, encapsulate the specific operation of payment, and return the PaymentIntent or Exception through the callback method

Before you start

We offer two methods for integrating Airwallex services. The first method provides pre-built user interfaces that you can directly invoke in your project. The second method provides low-level APIs, which require you to build your own user interfaces. You can choose the integration method based on your needs.

Airwallex Native UI integration

We provide native screens to facilitate the integration of payment functions.

Set up SDK

The Airwallex Android SDK is compatible with apps supporting Android API level 21 and above.

Install the SDK The Components are available through Maven Central, you only need to add the Gradle dependency.

To install the SDK, in your app-level build.gradle, add the following:

    dependencies {
        // It's required
        implementation 'io.github.airwallex:payment:5.0.2'
        
        // Select the payment method you want to support.
        implementation 'io.github.airwallex:payment-card:5.0.2'
        implementation 'io.github.airwallex:payment-redirect:5.0.2'
        implementation 'io.github.airwallex:payment-wechat:5.0.2'
        implementation 'io.github.airwallex:payment-googlepay:5.0.2'
    }

Configuration and preparation

After setting up the SDK, you are required to config your SDK with some parameters. Before using Airwallex SDK to confirm payment intents and complete the payments, you shall create payment intents in your own server, to make sure you maintain information in your own system

Configuration the SDK

We provide some parameters that can be used to debug the SDK, you can call it in Application

    AirwallexStarter.initialize(
        application,
        AirwallexConfiguration.Builder()
            .enableLogging(true)                // Enable log in sdk, and don’t forogt to set to false when it is ready to release
            .setEnvironment(Environment.DEMO)   // You can change the environment to STAGING, DEMO or PRODUCTION. It must be set to PRODUCTION when it is ready to release.
            .setSupportComponentProviders(
                listOf(
                    CardComponent.PROVIDER,
                    WeChatComponent.PROVIDER,
                    RedirectComponent.PROVIDER,
                    GooglePayComponent.PROVIDER
                )
            )
            .build(),
        ExampleClientSecretProvider()           // If you need to support recurring, you must provide your custom ClientSecretProvider
    )

Create Payment Intent (On the Merchant’s server)

Before confirming the PaymentIntent, You must create a PaymentIntent on the server and pass it to the client.

Follow these steps to create a PaymentIntent on the Merchant’s server

To begin you will need to obtain an access token to allow you to reach Airwallex API endpoints. Using your unique Client ID and API key (these can be generated within Account settings > API keys) you can call the Authentication API endpoint. On success, an access token will be granted.

Create customer(optional) allows you to save your customers’ details, attach payment methods so you can quickly retrieve the supported payment methods as your customer checks out on your shopping site. /api/v1/pa/customers/create

Finally, you need to create a PaymentIntent object on the Merchant’s server via /api/v1/pa/payment_intents/create and pass it to the client.

In the response of each payment intent, you will be returned with client_secret, which you will need to store for later uses.

After creating the payment intent, you can use Airwallex SDK to confirm payment intent and enable the shopper to complete the payment with selected payment methods

Edit shipping info

Use presentShippingFlow to allow users to provide a shipping address as well as select a shipping method. shipping parameter is optional.

    AirwallexStarter.presentShippingFlow(this, shipping,
        object : Airwallex.ShippingResultListener {
            override fun onCompleted(status: AirwallexShippingStatus) {

            }
        }
    )

Use the entire Native UI in one flow

For the redirect payment method. You need to configure scheme url on AndroidManifest.xml

    <intent-filter>
        ...
        <data
            android:host="${applicationId}"
            android:scheme="airwallexcheckout" />
    </intent-filter>

Use presentPaymentFlow to complete the entire payment flow. Needs to pass in a AirwallexSession object

    private fun buildSession(
        paymentIntent: PaymentIntent? = null,
        customerId: String? = null
    ): AirwallexSession {
        return when (checkoutMode) {
            AirwallexCheckoutMode.PAYMENT -> {
                AirwallexPaymentSession.Builder(
                    paymentIntent = requireNotNull(
                        paymentIntent,
                        { "PaymentIntent is required" }
                    ),
                    countryCode = Settings.countryCode,
                    googlePayOptions = GooglePayOptions(
                        billingAddressRequired = true,
                        billingAddressParameters = BillingAddressParameters(BillingAddressParameters.Format.FULL)
                    )
                )
                    .setReturnUrl(Settings.returnUrl)
                    .build()
            }
            AirwallexCheckoutMode.RECURRING -> {
                AirwallexRecurringSession.Builder(
                    customerId = requireNotNull(customerId, { "CustomerId is required" }),
                    currency = Settings.currency,
                    amount = BigDecimal.valueOf(Settings.price.toDouble()),
                    nextTriggerBy = nextTriggerBy,
                    countryCode = Settings.countryCode
                )
                    .setShipping(shipping)
                    .setRequireCvc(requiresCVC)
                    .setMerchantTriggerReason(if (nextTriggerBy == PaymentConsent.NextTriggeredBy.MERCHANT) PaymentConsent.MerchantTriggerReason.SCHEDULED else PaymentConsent.MerchantTriggerReason.UNSCHEDULED)
                    .setReturnUrl(Settings.returnUrl)
                    .build()
            }
            AirwallexCheckoutMode.RECURRING_WITH_INTENT -> {
                AirwallexRecurringWithIntentSession.Builder(
                    paymentIntent = requireNotNull(
                        paymentIntent,
                        { "PaymentIntent is required" }
                    ),
                    customerId = requireNotNull(
                        paymentIntent.customerId,
                        { "CustomerId is required" }
                    ),
                    nextTriggerBy = nextTriggerBy,
                    countryCode = Settings.countryCode
                )
                    .setRequireCvc(requiresCVC)
                    .setMerchantTriggerReason(if (nextTriggerBy == PaymentConsent.NextTriggeredBy.MERCHANT) PaymentConsent.MerchantTriggerReason.SCHEDULED else PaymentConsent.MerchantTriggerReason.UNSCHEDULED)
                    .setReturnUrl(Settings.returnUrl)
                    .build()
            }
        }
    }

    val session = buildSession(paymentIntent, customerId)
    AirwallexStarter.presentPaymentFlow(this, session,
        object : Airwallex.PaymentResultListener {
    
            override fun onCompleted(status: AirwallexPaymentStatus) {
                
            }
        }
    )

To obtain the payment result, you can use the retrievePaymentIntent method and check the latest status. Then you can prompt the shopper with the result.

    airwallex.retrievePaymentIntent(
        params = RetrievePaymentIntentParams(
            // the ID of the `PaymentIntent`, required.
            paymentIntentId = paymentIntentId,
            // the clientSecret of `PaymentIntent`, required.
            clientSecret = clientSecret
        ),
        listener = object : Airwallex.PaymentListener<PaymentIntent> {
            override fun onSuccess(response: PaymentIntent) {
                onComplete.invoke(response)
            }

            override fun onFailed(exception: AirwallexException) {
                Log.e(TAG, "Retrieve PaymentIntent failed", exception)
            }
        }
    )

Set up Google Pay

The Airwallex Android SDK allows merchants to provide Google Pay as a payment method to their customers by the following steps:

Make sure Google Pay is enabled on your Airwallex account.
Include the Google Pay module when installing the SDK as per Set up SDK.
You can customize the Google Pay options to restrict as well as provide extra context. For more information, please refer to GooglePayOptions class.

val googlePayOptions = GooglePayOptions(
    allowedCardAuthMethods = listOf("CRYPTOGRAM_3DS"),
    billingAddressParameters = BillingAddressParameters(BillingAddressParameters.Format.FULL),
    shippingAddressParameters = ShippingAddressParameters(listOf("AU", "CN"), true)
)
val paymentSession = AirwallexPaymentSession.Builder(
    paymentIntent = ...,
    countryCode = ...,
    googlePayOptions = googlePayOptions
)

We currently only support Visa and MasterCard for Google Pay, customers will only be able to select the cards of these payment networks during Google Pay.

Please note that our Google Pay module only supports AirwallexPaymentSession at the moment. We'll add support for recurring payment sessions in the future.

Custom Theme

You can overwrite these color values in your app. https://developer.android.com/guide/topics/ui/look-and-feel/themes#CustomizeTheme

    <color name="airwallex_tint_color">@color/airwallex_color_red</color>

Low-level API Integration

You can build your own entirely custom UI on top of our low-level APIs.

Step 1: Set up SDK

The Airwallex Android SDK is compatible with apps supporting Android API level 21 and above.

Install the SDK The Components are available through Maven Central, you only need to add the Gradle dependency.

To install the SDK, in your app-level build.gradle, add the following:

    dependencies {
        // It's required
        implementation 'io.github.airwallex:payment-components-core:5.0.2'
        
        // Select the payment method you want to support.
        implementation 'io.github.airwallex:payment-card:5.0.2'
        implementation 'io.github.airwallex:payment-googlepay:5.0.2'
    }

Step 2: Configuration and preparation

After setting up the SDK, you are required to config your SDK with some parameters. Before using Airwallex SDK to confirm payment intents and complete the payments, you shall create payment intents in your own server, to make sure you maintain information in your own system

Configuration the SDK

We provide some parameters that can be used to debug the SDK, you can call it in Application

    Airwallex.initialize(
        application,
        AirwallexConfiguration.Builder()
            .enableLogging(true)                // Enable log in sdk, and don’t forogt to set to false when it is ready to release
            .setEnvironment(Environment.DEMO)   // You can change the environment to STAGING, DEMO or PRODUCTION. It must be set to PRODUCTION when it is ready to release.
            .setSupportComponentProviders(
                listOf(
                    CardComponent.PROVIDER,
                    WeChatComponent.PROVIDER,
                    RedirectComponent.PROVIDER,
                    GooglePayComponent.PROVIDER
                )
            )
            .build(),
        ExampleClientSecretProvider()           // If you need to support recurring, you must provide your custom ClientSecretProvider
    )

Create Payment Intent

Create Payment Intent (On the Merchant’s server)

Step 3: Create AirwallexSession and Airwallex object

val session = buildSession(paymentIntent, customerId)
val airwallex = Airwallex(this@PaymentCartFragment)

Confirm card payment with card and billing details or payment consent ID

// Confirm intent with card and billing
airwallex.confirmPaymentIntent(
    session = session,
    card = PaymentMethod.Card.Builder()
        .setNumber("4012000300000021")
        .setName("John Citizen")
        .setExpiryMonth("12")
        .setExpiryYear("2029")
        .setCvc("737")
        .build(),
    billing = null,
    listener = object : Airwallex.PaymentResultListener {
        override fun onCompleted(status: AirwallexPaymentStatus) {
            // You can handle different payment statuses and perform UI action respectively here
        }
    }
)

// Or to confirm intent with a valid payment consent ID
airwallex.confirmPaymentIntent(
    session = session,
    paymentConsentId = "cst_xxxxxxxxxx",
    listener = object : Airwallex.PaymentResultListener {
        override fun onCompleted(status: AirwallexPaymentStatus) {
            // You can handle different payment statuses and perform UI action respectively here
        }
    }
)

Launch payment via Google Pay

Before invoking the payment API, you need to follow the steps to Set up Google Pay

// NOTE: We only support AirwallexPaymentSession (one off session), no recurring session for Google Pay at the moment.
// Also make sure you pass GooglePayOptions to the session. Refer to [Set up Google Pay].
airwallex.startGooglePay(
    session = session,
    listener = object : Airwallex.PaymentResultListener {
        override fun onCompleted(status: AirwallexPaymentStatus) {
            // You can handle different payment statuses and perform UI action respectively here
        }
    }
)

SDK Example

This sample app demonstrates integrating with the Airwallex Android SDK using its prebuilt UI components to manage the checkout flow, including specifying a shipping address and selecting a Payment Method.

To run the example project, you should follow these steps.

Run the following script to clone the repository to your local machine git clone git@github.com:airwallex/airwallex-payment-android.git
Open Android Studio and import the project by selecting the build.gradle file from the cloned repository
Go to Airwallex Account settings > API keys, then copy Client ID and API key to Settings.kt

    private const val BASE_URL = replace_with_base_url
    private const val API_KEY = replace_with_api_key
    private const val CLIENT_ID = replace_with_client_id

Register app on WeChat Pay, then copy App ID to Settings.kt

    private const val WECHAT_APP_ID = "put your WeChat app id here"

Run the sample project

Test Card Numbers

https://cardinaldocs.atlassian.net/wiki/spaces/CCen/pages/903577725/EMV+3DS+Test+Cases

Contributing

We welcome contributions of any kind including new features, bug fixes, and documentation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GUIDE.md

GUIDE.md

Airwallex Android SDK

Contents

Overview

Airwallex API

Airwallex Native UI

Before you start

Airwallex Native UI integration

Set up SDK

Configuration and preparation

Configuration the SDK

Create Payment Intent (On the Merchant’s server)

Edit shipping info

Use the entire Native UI in one flow

Set up Google Pay

Custom Theme

Low-level API Integration

Step 1: Set up SDK

Step 2: Configuration and preparation

Configuration the SDK

Create Payment Intent

Step 3: Create AirwallexSession and Airwallex object

Confirm card payment with card and billing details or payment consent ID

Launch payment via Google Pay

SDK Example

Test Card Numbers

Contributing

Files

GUIDE.md

Latest commit

History

GUIDE.md

File metadata and controls

Airwallex Android SDK

Contents

Overview

Airwallex API

Airwallex Native UI

Before you start

Airwallex Native UI integration

Set up SDK

Configuration and preparation

Configuration the SDK

Create Payment Intent (On the Merchant’s server)

Edit shipping info

Use the entire Native UI in one flow

Set up Google Pay

Custom Theme

Low-level API Integration

Step 1: Set up SDK

Step 2: Configuration and preparation

Configuration the SDK

Create Payment Intent

Step 3: Create AirwallexSession and Airwallex object

Confirm card payment with card and billing details or payment consent ID

Launch payment via Google Pay

SDK Example

Test Card Numbers

Contributing