Enable Super Qi — Quick Start

Turning on Pay with Super Qi is three decisions and one configuration change:

1. List it. Add ALIPAY to the SDK's availablePaymentMethods.
2. Decide who picks the method. Set paymentMethodChoice to ON_SDK (the SDK shows the picker — easiest) or ON_APP (your app shows it).
3. (Optional) Tune the Super Qi screen. Set aliPaySettings — which option shows first (QR/LINK) and whether to offer fallbacks.

Then initialize the SDK with that configuration. That's it.

Just want it working?

The simplest possible setup: include ALIPAY in the method list and use ON_SDK. The SDK then renders the "Pay by Card / Pay with Super Qi" chooser for you, with sensible Super Qi defaults (QR shown first). Everything else is fine-tuning.

---

Step 1 — Add ALIPAY to the available methods

availablePaymentMethods is the set of methods the SDK is allowed to offer. By default it contains only CARD and PAYMENT_TOKEN, so Super Qi is off until you add ALIPAY.

Step 2 — Choose where the method picker lives

Value	Who renders the "How do you want to pay?" screen	When to use
ON_SDK	The SDK	You want the least work — the SDK shows a polished, localized chooser including "Pay with Super Qi".
ON_APP	Your app	You already have your own payment-method screen and want to pass the chosen method into processPayment yourself.

Default differs from "on"

The SDK's built-in default for paymentMethodChoice is ON_APP. If you simply add ALIPAY to the list but leave the choice on ON_APP, the SDK will not show a chooser — your app is expected to drive the selection. For the quickest path to a visible "Pay with Super Qi" button, set paymentMethodChoice = ON_SDK.

Step 3 — Initialize with the configuration

Flutter

In this example app, the channel wrapper already accepts these as named parameters (defaults shown):

await PaymentSdkFlutter.initializeSDK(
  baseUrl: baseUrl,
  publicKey: publicKey,
  terminalId: terminalId,
  // 1. List Super Qi (ALIPAY) alongside card + saved tokens:
  availablePaymentMethods: const [
    PaymentMethodOption.CARD,
    PaymentMethodOption.ALIPAY,        // ← Pay with Super Qi
    PaymentMethodOption.PAYMENT_TOKEN,
  ],
  // 2. Let the SDK draw the picker:
  paymentMethodChoice: PaymentMethodChoice.ON_SDK,
  // 3. Show the QR option first on the Super Qi screen:
  aliPayShowFirst: AliPayShowFirst.QR,
);

See Flutter Integration for how these parameters travel down to the native SDK.

Android (Kotlin)

val availablePaymentMethods = setOf(
    AvailablePaymentMethods.CARD,
    AvailablePaymentMethods.ALIPAY,        // ← Pay with Super Qi
    AvailablePaymentMethods.PAYMENT_TOKEN
)

val aliPaySettings = AliPaySettings(
    showFirst = PaymentTypeAliPay.QR,      // QR option first
    qrToDeepLinkFallback = true,           // also offer "open Super Qi app"
    deepLinkToQrFallback = true            // also offer a QR when using the link
)

val config = PaymentSDKConfiguration.Builder()
    .setConnectionSettings(connectionSettings)
    .setMerchant(merchant)
    .setLocalization(localization)
    .setTheme(Theme.LIGHT)
    .setAvailablePaymentMethods(availablePaymentMethods)
    .setPaymentMethodChoice(PaymentMethodChoice.ON_SDK)
    .setAliPaySettings(aliPaySettings)
    .build()

PaymentSDK.initialize(this, config, sdkExitCallback)

iOS (Swift)

let availablePaymentMethods: Set<AvailablePaymentMethods> = [
    .CARD,
    .ALIPAY,        // ← Pay with Super Qi
    .PAYMENT_TOKEN
]

let aliPaySettings = AliPaySettings(
    showFirst: .QR,                 // QR option first
    qrToDeepLinkFallback: true,     // also offer "open Super Qi app"
    deepLinkToQrFallback: true      // also offer a QR when using the link
)

let config = PaymentSDKConfiguration(
    localization: localization,
    theme: theme,
    skipResultScreen: false,
    connectionSettings: connectionSettings,
    paymentMethodChoice: .onSdk,
    availablePaymentMethods: availablePaymentMethods,
    tdsSettings: tdsSettings,
    aliPaySettings: aliPaySettings
)

PaymentSDK.initialize(with: config)

---

Verify it worked

1. Launch the payment flow.
2. If paymentMethodChoice = ON_SDK, the method screen should now list "Pay with Super Qi" in addition to card.
3. Tap it — you should land on the Super Qi screen (QR or link first, per showFirst).

If the button doesn't appear, jump to Testing & Troubleshooting.

---

Optional — switch the configuration at runtime

You don't have to re-initialize the SDK to change methods. Each platform exposes a dynamic update so you can toggle Super Qi on an already-running SDK (handy for A/B tests or feature flags):

Flutter

await PaymentSdkFlutter.updatePaymentMethods(
  methods: const [PaymentMethodOption.CARD, PaymentMethodOption.ALIPAY],
  choice: PaymentMethodChoice.ON_SDK,
  aliPayShowFirst: AliPayShowFirst.LINK,
);

Android (Kotlin)

PaymentSDK.updateConfiguration(setOf(AvailablePaymentMethods.CARD, AvailablePaymentMethods.ALIPAY))
PaymentSDK.updateConfiguration(PaymentMethodChoice.ON_SDK)
PaymentSDK.updateConfiguration(AliPaySettings(PaymentTypeAliPay.LINK, true, true))

iOS (Swift)

sdk.updatePaymentSDKConfiguration(availablePaymentMethods: [.CARD, .ALIPAY])
sdk.updatePaymentSDKConfiguration(paymentMethodChoice: .onSdk)
sdk.updatePaymentSDKConfiguration(aliPaySettings: AliPaySettings(showFirst: .LINK, qrToDeepLinkFallback: true, deepLinkToQrFallback: true))

Next: Full Configuration Reference →