Prepare Payment Session

This page covers the required and optional setup steps for integrating the Airwallex Android SDK.

Environment

When your app starts, configure the SDK with the appropriate environment in your Application class.

Kotlin

1import com.airwallex.android.Airwallex
2import com.airwallex.android.core.AirwallexConfiguration
3import com.airwallex.android.core.Environment
4
5Airwallex.initialize(
6    AirwallexConfiguration.Builder()
7        .setEnvironment(Environment.DEMO)  // .DEMO, .STAGING, .PRODUCTION
8        .enableLogging(true)
9        .build()
10)

If you are using Hosted Payment Page, use AirwallexStarter.initialize() instead. For Embedded Payment Elements and Low-level API integration, use Airwallex.initialize() as shown above.

Create a customer

Generate or retrieve a customer ID for your user on your server-side. Refer to the Airwallex API documentation API for more details.

Optional if you only support guest checkout.

Create PaymentIntent

Your client app will need a PaymentIntent to form a payment session for Airwallex SDK to present payment flow.

From your server, access Airwallex API to Create Payment Intent API and pass the PaymentIntent returned to client app.

Create payment session object

The Airwallex Android SDK supports three types of payment sessions depending on your use case:

One-off payment session

Use this for single, non-recurring transactions where the payment amount and details are predetermined.

Option 1: Initialize with a pre-created payment intent

Kotlin

1import com.airwallex.android.core.AirwallexPaymentSession
2
3val session = AirwallexPaymentSession.Builder(
4    paymentIntent = paymentIntent,  // Created on your server
5    countryCode = "US"
6)
7    .setAutoCapture(true)  // Optional: auto-capture after authorization (card only)
8    .setReturnUrl("myapp://payment/return")  // Optional: app return URL
9    .build()

Option 2: Initialize with a payment intent provider (Express Checkout)

Using a PaymentIntentProvider allows the SDK to delay payment intent creation until just before payment confirmation or when clientSecret is required to request some Airwallex API.

Kotlin

1// 1. Implement PaymentIntentProvider
2class MyPaymentIntentProvider : PaymentIntentProvider {
3    override suspend fun createPaymentIntent(): PaymentIntent {
4        // Call your backend to create the payment intent
5        val response = MyBackendAPI.createPaymentIntent(
6            amount = 99.99,
7            currency = "USD"
8        )
9        return response.paymentIntent
10    }
11}
12
13// 2. Create session with the provider
14val provider = MyPaymentIntentProvider()
15val session = AirwallexPaymentSession.Builder(
16    paymentIntentProvider = provider,  // Payment intent will be created when needed
17    countryCode = "US"
18)
19    .setAutoCapture(true)
20    .build()

Recurring payment session

Use this for subscription-based or recurring charge scenarios where you manage the billing cycle.

Option 1: Initialize with customer details

Kotlin

1import com.airwallex.android.core.AirwallexRecurringSession
2
3val session = AirwallexRecurringSession.Builder(
4    customerId = customerId,
5    clientSecret = clientSecret,
6    currency = "USD",
7    amount = 99.99,
8    countryCode = "US",
9    nextTriggerBy = nextTriggerBy  // Next billing trigger type
10)
11    .setMerchantTriggerReason(MerchantTriggerReason.SCHEDULED)  // Optional
12    .setReturnUrl("myapp://payment/return")  // Optional: app return URL
13    .build()

Key parameters:

customerId: Customer ID from your backend
clientSecret: Client secret from customer creation
nextTriggerBy: Next billing trigger type (.CUSTOMER or .MERCHANT)

Option 2: Initialize with a payment intent provider (Express Checkout)

Kotlin

1class MyRecurringIntentProvider : PaymentIntentProvider {
2    override suspend fun createPaymentIntent(): PaymentIntent {
3        val response = MyBackendAPI.createRecurringPaymentIntent(
4            customerId = customerId,
5            amount = 99.99,
6            currency = "USD"
7        )
8        return response.paymentIntent
9    }
10}
11
12val provider = MyRecurringIntentProvider()
13val session = AirwallexRecurringSession.Builder(
14    paymentIntentProvider = provider,
15    customerId = customerId,
16    clientSecret = clientSecret,
17    currency = "USD",
18    amount = 99.99,
19    countryCode = "US",
20    nextTriggerBy = NextTriggerBy.MERCHANT/CUSTOMER
21).build()

Recurring payment with intent session

Use this to combine recurring billing with an explicit payment intent, useful for initial setup transactions in subscription flows.

Option 1: Initialize with a pre-created payment intent

Kotlin

1import com.airwallex.android.core.AirwallexRecurringWithIntentSession
2
3val session = AirwallexRecurringWithIntentSession.Builder(
4    paymentIntent = paymentIntent,
5    customerId = customerId,
6    clientSecret = clientSecret,
7    currency = "USD",
8    amount = 99.99,
9    countryCode = "US",
10    nextTriggerBy = nextTriggerBy
11)
12    .setMerchantTriggerReason(MerchantTriggerReason.SCHEDULED)  // Optional
13    .setReturnUrl("myapp://payment/return")  // Optional: app return URL
14    .build()

This variant links a specific payment intent to recurring payment arrangements, allowing you to capture an initial charge while establishing future billing authorization.

Option 2: Initialize with a payment intent provider (Express Checkout)

Kotlin

1class MyRecurringWithIntentProvider : PaymentIntentProvider {
2    override suspend fun createPaymentIntent(): PaymentIntent {
3        val response = MyBackendAPI.createRecurringWithIntentPayment(
4            customerId = customerId,
5            amount = 99.99,
6            currency = "USD"
7        )
8        return response.paymentIntent
9    }
10}
11
12val provider = MyRecurringWithIntentProvider()
13val session = AirwallexRecurringWithIntentSession.Builder(
14    paymentIntentProvider = provider,
15    customerId = customerId,
16    clientSecret = clientSecret,
17    currency = "USD",
18    amount = 99.99,
19    countryCode = "US",
20    nextTriggerBy = NextTriggerBy.MERCHANT/CUSTOMER
21).build()

WeChat Pay

To enable WeChat Pay:

Make sure you add dependency for payment-wechat module
Register your app at WeChat Pay to get a WeChat app ID
Configure the WeChat app ID in your Airwallex account

During SDK initialization, ensure WeChatComponent.PROVIDER is added:

Kotlin

1import com.airwallex.android.Airwallex
2import com.airwallex.android.core.AirwallexConfiguration
3
4Airwallex.initialize(
5    AirwallexConfiguration.Builder()
6        .setEnvironment(Environment.DEMO)
7        .setSupportComponentProviders(
8            listOf(
9                CardComponent.PROVIDER,
10                WeChatComponent.PROVIDER,  // Enable WeChat Pay
11                RedirectComponent.PROVIDER
12            )
13        )
14        .build()
15)

After completing payment, WeChat will redirect to your app. The SDK handles the callback automatically and you will receive the payment result through the payment completion callbacks (onPaymentResult or PaymentResultListener).

Google Pay

To enable Google Pay:

Make sure you add dependency for payment-googlepay module
Set up Google Pay in your app. For more information, refer to Google's official documentation .
Make sure Google Pay is enabled on your Airwallex account.
Configure googlePayOptions on the payment session object.

During SDK initialization, ensure GooglePayComponent.PROVIDER is added:

Kotlin

1import com.airwallex.android.Airwallex
2import com.airwallex.android.core.AirwallexConfiguration
3
4Airwallex.initialize(
5    AirwallexConfiguration.Builder()
6        .setEnvironment(Environment.DEMO)
7        .setSupportComponentProviders(
8            listOf(
9                CardComponent.PROVIDER,
10                GooglePayComponent.PROVIDER,  // Enable Google Pay
11                RedirectComponent.PROVIDER
12            )
13        )
14        .build()
15)

You can customize the Google Pay options and configure them on the payment session:

Kotlin

1import com.airwallex.android.googlepay.GooglePayOptions
2
3val googlePayOptions = GooglePayOptions(
4    allowedCardAuthMethods = listOf("PAN_ONLY", "CRYPTOGRAM_3DS"),
5    merchantName = "Your Merchant Name",
6    billingAddressRequired = true,
7    billingAddressParameters = GooglePayOptions.BillingAddressParameters(
8        format = GooglePayOptions.BillingAddressFormat.FULL,
9        phoneNumberRequired = true
10    )
11)
12
13val session = AirwallexPaymentSession.Builder(
14    paymentIntent = paymentIntent,
15    countryCode = "US"
16)
17    .setGooglePayOptions(googlePayOptions)  // Configure Google Pay options
18    .build()

When setting up your Google Pay registration, use the following Airwallex details when you are requested to provide your gateway information to tokenize card details: gateway: airwallex gatewayMerchantId: Your merchant name as registered with Airwallex

We currently support the following payment networks for Google Pay: Visa, MasterCard, ChinaUnionPay, Maestro, Amex, Discover, and JCB. Coupon is not supported at this stage.

Redirect

For payment methods that require browser redirects (for example, Alipay, PayPal), you need to configure a return URL and handle the redirect flow.

Configure return URL

Set the return URL on your payment session. This URL is where the shopper will be redirected after completing the payment on the external payment provider's page:

Kotlin

1val session = AirwallexPaymentSession.Builder(
2    paymentIntent = paymentIntent,
3    countryCode = "US"
4)
5    .setReturnUrl("myapp://payment/return")  // Configure your app's deep link
6    .build()

Handle payment result

The SDK automatically handles the redirect flow. After the shopper completes the payment and is redirected back to your app, you will receive the payment result through the payment completion callbacks (onPaymentResult or PaymentResultListener).

A completed flow does NOT imply a successful transaction. You need to query the payment result afterwards through your server to confirm whether the payment was successful. From your server, retrieve the Payment Intent API, get the payment result within it and return it to client app.

Was this page helpful?