Prepare Session object

Copy for LLMView as Markdown

This page covers the required and optional setup steps for integrating the Airwallex Android SDK. Make sure you have completed Before you start to install and initialize the SDK before continuing.

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.

The payment intent is a required object for all transaction modes in the Airwallex Android SDK. It represents a specific payment attempt and must be created before initiating a payment from the mobile app.

Create payment intent on your server-side and then pass the payment intent to the mobile-side to confirm the payment intent with the payment method selected.

Refer to the Airwallex API documentation API for details of the payment intent API.

While creating payment intent using payment_intents/create:

If amount = 0, PaymentConsentOptions is required — only a payment consent will be created (no funds will be deducted).
If amount > 0, a payment will be processed. If PaymentConsentOptions is also set, a consent will be created alongside the payment.
For guest checkout, customer_id parameter can be omitted.

Create Session object

Session is the unified session type that supports one-off payments, recurring payments, and CIT/MIT consents through a single API. Which flow runs is determined by PaymentConsentOptions and the PaymentIntent amount:

Flow	`PaymentConsentOptions`	`amount`	`customerId`
One-off payment	not set	> 0	optional
Recurring (consent only, no charge)	set	0	required
Recurring with intent (consent + charge)	set	> 0	required

PaymentConsentOptions accepts the following values:

nextTriggeredBy — MERCHANT (MIT) or CUSTOMER (CIT)
merchantTriggerReason (only applicable when nextTriggeredBy = MERCHANT) — SCHEDULED, UNSCHEDULED, or INSTALLMENTS

Option 1: Initialize with a pre-created payment intent

Kotlin

1import com.airwallex.android.core.Session
2import com.airwallex.android.core.model.PaymentConsent
3import com.airwallex.android.core.model.PaymentConsentOptions
4import com.airwallex.android.core.model.PaymentIntent
5
6val paymentConsentOptions = if (/* one-off transaction */) {
7    null
8} else {
9    /* recurring transaction */
10    PaymentConsentOptions(
11        nextTriggeredBy = PaymentConsent.NextTriggeredBy.MERCHANT, // .MERCHANT or .CUSTOMER
12        merchantTriggerReason = PaymentConsent.MerchantTriggerReason.UNSCHEDULED // .SCHEDULED, .UNSCHEDULED, or .INSTALLMENTS
13    )
14}
15
16val session = Session.Builder(
17    paymentIntent = paymentIntent, // payment intent created on your server
18    countryCode = "Your country code",
19    googlePayOptions = googlePayOptions // required if you want to support Google Pay
20)
21    .setPaymentConsentOptions(paymentConsentOptions) // info for recurring transactions
22    .setAutoCapture(true) // Only applicable for card payment. If true the payment will be captured immediately after authorization succeeds.
23    .setRequireBillingInformation(true) // prefilled billing address requirement
24    .setReturnUrl("myapp://payment/return") // App return url
25    .build()

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

Using a PaymentIntentSource (or the callback-based PaymentIntentProvider for Java) allows the SDK to delay payment intent creation until just before payment confirmation or when clientSecret is required to request some Airwallex API.

The same three flows apply: the amount you expose on your PaymentIntentSource (and echo in the returned PaymentIntent) drives which flow runs, and setPaymentConsentOptions(...) is required for both recurring variants. customerId on the builder is required for recurring flows and optional for one-off payments.

Kotlin

1import com.airwallex.android.core.PaymentIntentSource
2import com.airwallex.android.core.Session
3import com.airwallex.android.core.model.PaymentConsent
4import com.airwallex.android.core.model.PaymentConsentOptions
5import com.airwallex.android.core.model.PaymentIntent
6import java.math.BigDecimal
7
8// 1. Implement PaymentIntentSource
9class MyPaymentIntentSource(
10    override val amount: BigDecimal, // 0 for recurring (no charge), > 0 otherwise
11    override val currency: String = "USD",
12    val customerId: String? = null // required for recurring flows, optional for one-off
13) : PaymentIntentSource {
14    override suspend fun getPaymentIntent(): PaymentIntent {
15        // Call your backend to create the payment intent.
16        // Its `amount` must match the `amount` exposed by this source,
17        // and its `customerId` must match the one on the session builder for recurring flows.
18        return myApiService.createPaymentIntent(
19            amount = amount,
20            currency = currency,
21            customerId = customerId
22        )
23    }
24}
25
26// 2. Create session with the source
27val source = MyPaymentIntentSource(
28    amount = BigDecimal("10.00"),
29    customerId = customerId
30)
31val session = Session.Builder(
32    paymentIntentSource = source, // Payment intent will be created when needed
33    countryCode = "US",
34    customerId = customerId // required for recurring flows, optional for one-off
35)
36    .setReturnUrl("myapp://payment/return")
37    .build()

Prefer PaymentIntentSource for Kotlin/coroutine code. For Java, use the callback-based PaymentIntentProvider constructor instead — the builder and PaymentConsentOptions rules are identical.

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 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 Session:

Kotlin

1import com.airwallex.android.core.Session
2import com.airwallex.android.googlepay.GooglePayOptions
3
4val googlePayOptions = GooglePayOptions(
5    allowedCardAuthMethods = listOf("PAN_ONLY", "CRYPTOGRAM_3DS"),
6    merchantName = "Your Merchant Name",
7    billingAddressRequired = true,
8    billingAddressParameters = GooglePayOptions.BillingAddressParameters(
9        format = GooglePayOptions.BillingAddressFormat.FULL,
10        phoneNumberRequired = true
11    )
12)
13
14val session = Session.Builder(
15    paymentIntent = paymentIntent,
16    countryCode = "US",
17    googlePayOptions = googlePayOptions // required for Google Pay
18)
19    .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. Google Pay does not support recurring or recurring-with-intent flows for CIT payment.

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 Session. This URL is where the shopper will be redirected after completing the payment on the external payment provider's page:

Kotlin

1val session = Session.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?