Hosted Payment Page integration

Copy for LLMView as Markdown

This guide covers UI integration using the Hosted Payment Page (HPP) approach. Make sure you add dependencies for the core payment module and payment method modules you want to support.

How it works

The diagram below depicts the integration flow for a card payment.

Card one-off integration flow

Prepare payment session

Before launching the payment UI, you need to create a payment session. See Prepare payment session for details on setting up the environment, creating a customer, payment intent, and payment session.

Complete payment flow (recommended)

This is the recommended usage. It launches the entire payment experience, including payment method selection and checkout. The SDK manages the complete checkout experience.

Kotlin example

Kotlin

1import com.airwallex.android.AirwallexStarter
2import com.airwallex.android.core.Airwallex
3import com.airwallex.android.core.AirwallexPaymentStatus
4import com.airwallex.android.core.PaymentMethodsLayoutType
5import com.airwallex.android.core.Appearance
6import com.airwallex.android.view.composables.PaymentElementConfiguration
7
8val configuration = PaymentElementConfiguration.PaymentSheet(
9    layout = PaymentMethodsLayoutType.ACCORDION,  // or .TAB
10    googlePayButton = PaymentElementConfiguration.GooglePayButton(
11        showsAsPrimaryButton = true,
12        buttonType = null  // optional
13    ),
14    checkoutButton = PaymentElementConfiguration.CheckoutButton(title = "Pay Now"),
15    appearance = Appearance(
16        themeColor = 0xFF612FFF.toInt(),
17        isDarkTheme = null  // null = follow system
18    )
19)
20
21AirwallexStarter.presentEntirePaymentFlow(
22    activity = this,
23    session = session,
24    configuration = configuration,
25    paymentResultListener = object : Airwallex.PaymentResultListener {
26        override fun onCompleted(status: AirwallexPaymentStatus) {
27            handlePaymentResult(status)
28        }
29    }
30)
31
32private fun handlePaymentResult(status: AirwallexPaymentStatus) {
33    when (status) {
34        is AirwallexPaymentStatus.Success -> {
35            // Payment successful
36            showSuccess(status.paymentIntentId)
37        }
38        is AirwallexPaymentStatus.Failure -> {
39            // Payment failed
40            showError(status.exception.message)
41        }
42        is AirwallexPaymentStatus.Cancel -> {
43            // Payment cancelled by user
44            showCancelled()
45        }
46        is AirwallexPaymentStatus.InProgress -> {
47            // Payment in progress
48        }
49    }
50}

Java example

Java

1import com.airwallex.android.AirwallexStarter;
2import com.airwallex.android.core.Airwallex;
3import com.airwallex.android.core.AirwallexPaymentStatus;
4import com.airwallex.android.core.PaymentMethodsLayoutType;
5import com.airwallex.android.core.Appearance;
6import com.airwallex.android.view.composables.PaymentElementConfiguration;
7
8PaymentElementConfiguration configuration = 
9    new PaymentElementConfiguration.PaymentSheet(
10        PaymentMethodsLayoutType.ACCORDION,  // or TAB
11        new PaymentElementConfiguration.GooglePayButton(
12            true,  // showsAsPrimaryButton
13            null   // buttonType (optional)
14        ),
15        new PaymentElementConfiguration.CheckoutButton("Pay Now"),
16        new Appearance(
17            0xFF612FFF,  // themeColor
18            null         // isDarkTheme (null = follow system)
19        )
20    );
21
22AirwallexStarter.presentEntirePaymentFlow(
23    this,
24    session,
25    configuration,
26    new Airwallex.PaymentResultListener() {
27        @Override
28        public void onCompleted(@NonNull AirwallexPaymentStatus status) {
29            if (status instanceof AirwallexPaymentStatus.Success) {
30                showSuccess(((AirwallexPaymentStatus.Success) status).getPaymentIntentId());
31            } else if (status instanceof AirwallexPaymentStatus.Failure) {
32                showError(((AirwallexPaymentStatus.Failure) status).getException().getMessage());
33            } else if (status instanceof AirwallexPaymentStatus.Cancel) {
34                showCancelled();
35            }
36        }
37    }
38);

Card-only payment flow

Display only the card payment UI. This restricts the payment options to cards exclusively.

Kotlin example

Kotlin

1import com.airwallex.android.AirwallexStarter
2import com.airwallex.android.core.Airwallex
3import com.airwallex.android.core.AirwallexPaymentStatus
4import com.airwallex.android.core.AirwallexSupportedCard
5import com.airwallex.android.core.Appearance
6import com.airwallex.android.view.composables.PaymentElementConfiguration
7
8val configuration = PaymentElementConfiguration.Card(
9    supportedCardBrands = listOf(
10        AirwallexSupportedCard.VISA,
11        AirwallexSupportedCard.MASTERCARD,
12        AirwallexSupportedCard.UNIONPAY
13    ),
14    checkoutButton = PaymentElementConfiguration.CheckoutButton(title = "Pay Now"),
15    appearance = Appearance(
16        themeColor = 0xFF612FFF.toInt(),
17        isDarkTheme = null  // null = follow system
18    )
19)
20
21AirwallexStarter.presentCardPaymentFlow(
22    activity = this,
23    session = session,
24    configuration = configuration,
25    paymentResultListener = object : Airwallex.PaymentResultListener {
26        override fun onCompleted(status: AirwallexPaymentStatus) {
27            handlePaymentResult(status)
28        }
29    }
30)

Java example

Java

1import com.airwallex.android.AirwallexStarter;
2import com.airwallex.android.core.AirwallexSupportedCard;
3import com.airwallex.android.core.Appearance;
4import com.airwallex.android.view.composables.PaymentElementConfiguration;
5import java.util.Arrays;
6
7PaymentElementConfiguration configuration = 
8    new PaymentElementConfiguration.Card(
9        Arrays.asList(
10            AirwallexSupportedCard.VISA,
11            AirwallexSupportedCard.MASTERCARD,
12            AirwallexSupportedCard.UNIONPAY
13        ),
14        new PaymentElementConfiguration.CheckoutButton("Pay Now"),
15        new Appearance(
16            0xFF612FFF,  // themeColor
17            null         // isDarkTheme (null = follow system)
18        )
19    );
20
21AirwallexStarter.presentCardPaymentFlow(
22    this,
23    session,
24    configuration,
25    new Airwallex.PaymentResultListener() {
26        @Override
27        public void onCompleted(@NonNull AirwallexPaymentStatus status) {
28            handlePaymentResult(status);
29        }
30    }
31);

Use this when your merchant account supports only card-based transactions or you want to streamline checkout to accept cards exclusively.

Card payment dialog

Display card entry in a dialog format rather than a full-screen activity. This is optimal for modal card collection experiences, such as adding payment methods within account settings.

Kotlin example

Kotlin

1import com.airwallex.android.view.AirwallexAddPaymentDialog
2import com.airwallex.android.core.Airwallex
3import com.airwallex.android.core.AirwallexPaymentStatus
4import com.airwallex.android.core.AirwallexSupportedCard
5import com.airwallex.android.core.Appearance
6import com.airwallex.android.view.composables.PaymentElementConfiguration
7
8val configuration = PaymentElementConfiguration.Card(
9    supportedCardBrands = listOf(
10        AirwallexSupportedCard.VISA,
11        AirwallexSupportedCard.MASTERCARD,
12        AirwallexSupportedCard.UNIONPAY
13    ),
14    checkoutButton = PaymentElementConfiguration.CheckoutButton(title = "Add Card"),
15    appearance = Appearance(
16        themeColor = 0xFF612FFF.toInt(),
17        isDarkTheme = null
18    )
19)
20
21val dialog = AirwallexAddPaymentDialog(
22    activity = this,
23    session = session,
24    configuration = configuration,
25    paymentResultListener = object : Airwallex.PaymentResultListener {
26        override fun onCompleted(status: AirwallexPaymentStatus) {
27            handlePaymentResult(status)
28        }
29    }
30)
31dialog.show()

Java example

Java

1import com.airwallex.android.view.AirwallexAddPaymentDialog;
2import com.airwallex.android.core.AirwallexSupportedCard;
3import com.airwallex.android.core.Appearance;
4import com.airwallex.android.view.composables.PaymentElementConfiguration;
5import java.util.Arrays;
6
7PaymentElementConfiguration configuration = 
8    new PaymentElementConfiguration.Card(
9        Arrays.asList(
10            AirwallexSupportedCard.VISA,
11            AirwallexSupportedCard.MASTERCARD,
12            AirwallexSupportedCard.UNIONPAY
13        ),
14        new PaymentElementConfiguration.CheckoutButton("Add Card"),
15        new Appearance(
16            0xFF612FFF,  // themeColor
17            null         // isDarkTheme (null = follow system)
18        )
19    );
20
21AirwallexAddPaymentDialog dialog = new AirwallexAddPaymentDialog(
22    this,
23    session,
24    configuration,
25    new Airwallex.PaymentResultListener() {
26        @Override
27        public void onCompleted(@NonNull AirwallexPaymentStatus status) {
28            handlePaymentResult(status);
29        }
30    }
31);
32dialog.show();

The configuration parameter is optional and defaults to PaymentElementConfiguration.Card() which accepts all card brands. You can omit it for default behavior or customize it to control supported cards, checkout button text, and appearance.

Configuration options

We provide TAB and ACCORDION styles for our payment sheet:

Tab	Accordion

Complete payment flow configuration

When calling presentEntirePaymentFlow, you can configure:

Property	Type	Description	Default
`layout`	`PaymentMethodsLayoutType`	`.TAB` or `.ACCORDION` layout style	`.TAB`
`googlePayButton`	`GooglePayButton`	Configure Google Pay button appearance	`GooglePayButton()`
`checkoutButton`	`CheckoutButton`	Customize checkout button text	`CheckoutButton()`
`appearance`	`Appearance?`	Customize theme colors and dark mode	`null`

Kotlin

1import com.airwallex.android.AirwallexStarter
2import com.airwallex.android.core.PaymentMethodsLayoutType
3import com.airwallex.android.core.Appearance
4import com.airwallex.android.view.composables.PaymentElementConfiguration
5
6val configuration = PaymentElementConfiguration.PaymentSheet(
7    layout = PaymentMethodsLayoutType.ACCORDION,  // or .TAB
8    googlePayButton = PaymentElementConfiguration.GooglePayButton(showsAsPrimaryButton = true),
9    checkoutButton = PaymentElementConfiguration.CheckoutButton(title = "Pay Now"),
10    appearance = Appearance(
11        themeColor = 0xFF612FFF.toInt(),
12        isDarkTheme = null
13    )
14)
15
16AirwallexStarter.presentEntirePaymentFlow(
17    activity = this,
18    session = session,
19    configuration = configuration,
20    paymentResultListener = paymentResultListener
21)

Card-only payment flow configuration

When calling presentCardPaymentFlow, you can configure:

Property	Type	Description	Default
`supportedCardBrands`	`List<AirwallexSupportedCard>`	Accepted card brands	All available brands
`checkoutButton`	`CheckoutButton`	Customize checkout button text	`CheckoutButton()`
`appearance`	`Appearance?`	Customize theme colors and dark mode	`null`

Supported card brands include: VISA, MASTERCARD, AMEX, DISCOVER, JCB, DINERSCLUB, UNIONPAY.

Kotlin

1import com.airwallex.android.core.AirwallexSupportedCard
2import com.airwallex.android.core.Appearance
3import com.airwallex.android.view.composables.PaymentElementConfiguration
4
5val configuration = PaymentElementConfiguration.Card(
6    supportedCardBrands = listOf(
7        AirwallexSupportedCard.VISA,
8        AirwallexSupportedCard.MASTERCARD,
9        AirwallexSupportedCard.UNIONPAY
10    ),
11    checkoutButton = PaymentElementConfiguration.CheckoutButton(title = "Pay Now"),
12    appearance = Appearance(
13        themeColor = 0xFF612FFF.toInt(),
14        isDarkTheme = null
15    )
16)
17
18AirwallexStarter.presentCardPaymentFlow(
19    activity = this,
20    session = session,
21    configuration = configuration,
22    paymentResultListener = paymentResultListener
23)

Shared configuration objects

GooglePayButton:

Property	Type	Description	Default
`showsAsPrimaryButton`	`Boolean`	Display Google Pay as a prominent button vs. in the payment method list	`true`
`buttonType`	`GooglePayButtonType?`	Button type (for example, `STANDARD`, `BUY`, `DONATE`)	`null`

CheckoutButton:

Property	Type	Description	Default
`title`	`String?`	Custom text for the checkout button (for example, "Pay Now", "Complete Purchase"). If `null`, defaults to "Pay" or "Confirm"	`null`

Appearance:

Property	Type	Description	Default
`themeColor`	`Int?`	Primary brand color in ARGB format (for example, `0xFF612FFF`)	`null`
`isDarkTheme`	`Boolean?`	`true` (force dark), `false` (force light), `null` (follow system)	`null`

Session configuration

When creating AirwallexPaymentSession, you can filter which payment methods are available:

Kotlin

1import com.airwallex.android.core.AirwallexPaymentSession
2
3val session = AirwallexPaymentSession.Builder(
4    paymentIntent = paymentIntent,
5    countryCode = "US"
6)
7    .setPaymentMethods(
8        listOf("card")  // Show only card payment
9    )
10    .build()

You can also customize the payment methods and their order:

Kotlin

1val session = AirwallexPaymentSession.Builder(
2    paymentIntent = paymentIntent,
3    countryCode = "US"
4)
5    .setPaymentMethods(
6        listOf("paypal", "card", "googlepay", "fps", "alipayhk")
7    )
8    .build()

Available payment method names can be found in the Airwallex API documentation API.

Handle payment result

The PaymentResultListener interface provides callbacks for payment lifecycle events through the onCompleted() method. The AirwallexPaymentStatus parameter communicates the transaction outcome:

Payment status types

Status	Description
`AirwallexPaymentStatus.Success`	Payment processed successfully
`AirwallexPaymentStatus.Failure`	Transaction declined or error occurred
`AirwallexPaymentStatus.Cancel`	User dismissed the payment UI
`AirwallexPaymentStatus.InProgress`	Awaiting authentication (for example, 3D Secure)

If a payment consent is created during the payment process, you can retrieve the consent ID from the consentId property of AirwallexPaymentStatus.Success for any further usage.

Was this page helpful?