Flutter SDK | Wonder Developer Documentation

The Flutter SDK lets you embed Wonder Payment Gateway's payment flow into your Flutter application.

Workflow

Initiate the Flutter SDK

To initiate the SDK, you need to know:

Set up the Payment Configurations. Retrieve appID as a first step when initiating the SDK when you onboard on Wonder, in order to get access to our Payment Gateway configurations.
For Flutter SDK, Wechat Pay, Google Pay and Apple Pay, you will be required to apply directly with the schemes to obtain the unique identifier, for the activation of those methods.
To set up a method for future payments, you must generate a customer UUID for the Tokenisation process.
Customer can opt to customise the UI of the payment elements, or follow the default UI settings.

pubspec.yaml

Add the SDK dependency via pub:

text

dependencies:
  wonder_payment_plugin: ^x.x.x

iOS Configuration files

The Flutter SDK wraps the native iOS SDK, so the same iOS configuration is required.

Add URL types

text

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>payment_sdk_demo</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_APP_SCHEME</string>
    </array>
  </dict>
</array>

INFO

YOUR_APP_SCHEME here must match fromScheme in your payment config.

Add whitelist

Declare which external apps your app is allowed to query and launch, so payment apps like WeChat Pay, Alipay, and Octopus can be opened. This is the opposite direction from URL types: whitelist lets your app open other apps, while URL types lets other apps return to yours.

text

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>weixin</string>
    <string>weixinULAPI</string>
    <string>weixinURLParamsAPI</string>
    <string>uppaysdk</string>
    <string>uppaywallet</string>
    <string>uppayx1</string>
    <string>uppayx2</string>
    <string>uppayx3</string>
    <string>octopus</string>
    <string>alipayhk</string>
    <string>alipays</string>
</array>

WeChatPay dependency

Required only if you use WeChat Pay. Without this, WeChat Pay cannot redirect back to your app.

text

<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLName</key>
		<string>wechat_pay</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>YOUR_WECHAT_APP_ID</string>
		</array>
	</dict>
</array>

INFO

YOUR_WECHAT_APP_ID must match WechatConfig.appId in your payment config.

Handle redirect in AppDelegate.swift

Receive the redirect from third-party payment apps and pass it to the SDK.

text

func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    return WonderPayment.handleOpenURL(url: url)
}

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return WonderPayment.handleOpenURL(url: url)
}

INFO

Without this, the SDK cannot receive the payment result when the user returns from WeChat or Alipay or other payment methods.

Android Configuration files

The Flutter SDK wraps the native Android SDK, so the same Android configuration is required.

Add the repository

Add the Wonder Maven repository in your project-level build.gradle:

text

dependencyResolutionManagement {
  repositories {
    mavenCentral()
    maven {
      url 'https://raw.githubusercontent.com/wonder-sources/WonderPayment-Android/master'
    }
  }
}

Register result Activities

Register a result Activity for each third-party payment channel you use. Each channel redirects back to your app through its own Activity and URL scheme. Only add the ones you actually enable.

text

<!-- WeChat Pay: Create an empty Activity in the application package name directory -->
<activity-alias
    android:name=".wxapi.WXPayEntryActivity"
    android:exported="true"
    android:targetActivity="com.wonder.payment.sdk.wxapi.WXPayEntryResultActivity" />

<!-- Alipay Auto Debit -->
<activity
    android:name="com.wonder.payment.sdk.activity.AlipayResultActivity"
    android:exported="true"
    android:launchMode="singleTask"
    android:taskAffinity="${applicationId}"
    android:theme="@android:style/Theme.Translucent.NoTitleBar">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="alipay"
            android:scheme="paydemo" />
    </intent-filter>
</activity>

<!-- Payme -->
<activity
    android:name="com.wonder.payment.sdk.activity.PaymeResultActivity"
    android:exported="true"
    android:launchMode="singleTask"
    android:taskAffinity="${applicationId}"
    android:theme="@android:style/Theme.Translucent.NoTitleBar">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="payme"
            android:scheme="paydemo" />
    </intent-filter>
</activity>

INFO

paydemo here must match fromScheme in your payment config.

Flutter SDK configuration

The Flutter SDK takes 2 configuration objects:

Object	Controls	Example
PaymentConfig	How the payment behaves — merchant identity, environment, payment methods.	`appId`,`environment`,`applePay`.
UIConfig	How the checkout looks — colors, radius, interaction style	`background`,`borderRadius`.

text


WonderPaymentPlugin.init(
    paymentConfig: PaymentConfig(
      environment: PaymentEnvironment.staging, // [staging | alpha | production]
      appId: "YOUR_APP_ID",
      fromScheme: "YOUR_APP_SCHEME",
      wechat: WechatConfig(
        appId: "WECHAT_APP_ID",
        universalLink: "YOUR_APP_UNIVERSAL_LINK",
      ),
      applePay: ApplePayConfig(
        merchantIdentifier: 'YOUR_MERCHANT_IDENTIFIER',
        merchantName: 'YOUR_MERCHANT_NAME',
        countryCode: 'HK',
      ),
      googlePay: GooglePayConfig(
        merchantName: 'YOUR_MERCHANT_NAME',
        merchantId: 'YOUR_MERCHANT_IDENTIFIER',
        countryCode: 'HK',
        currencyCode: 'HKD',
      ),
    ),
    uiConfig: UIConfig(
      displayStyle: DisplayStyle.confirm,
    ),
  );

PaymentConfig

Field	Required	Description
appId	`Yes`	The APP ID generated on Wonder Dashboard.
customerId	`No`	Needed for tokenisation. Create via create customerAPI.
fromscheme	`Yes`	Used to redirect back to your app after app-to-app payment.
environment	`No`	Available parameter:`PaymentEnvironment.staging`, `PaymentEnvironment.alpha`,`PaymentEnvironment.production`.
locale	`No`	Available parameter:`.zh_CN`, `.zh_HK`,`.en_US`.
wechat	`No`	Enable WeChat Pay.
WechatConfig.appId	`Yes`	The appId applied on WeChat Pay.
WechatConfig.universalLink	`Yes`	The official website of the merchant's app.
applePay	`No`	Enable Apple Pay.
ApplePayConfig.merchantIdentifier	`Yes`	Apple merchant identifier.
ApplePayConfig.merchantName	`Yes`	Merchant display name for Apple Pay.
ApplePayConfig.countryCode	`Yes`	Two-letter ISO 3166 country code.
googlePay	`No`	Enable Google Pay.
GoogleConfig.countryCode	`Yes`	ISO 3166-1 alpha-2 country code where the transaction is processed.
GoogleConfig.currencyCode	`Yes`	The ISO 4217 alphabetic currency code.
GoogleConfig.merchantId	`Yes`	A Google merchant identifier issued after registration with the Google Pay & Wallet Console.
GoogleConfig.merchantName	`Yes`	Merchant name encoded as UTF-8. Merchant name is rendered in the payment sheet.

UIConfig

Field	Required	Description
background	`No`	Default: #FFFFFF
secondaryBackground	`No`	Default: #F7F8F9
primaryTextColor	`No`	Default: #000000
secondaryTextColor	`No`	Default: #8E8E93
primaryButtonColor	`No`	Default: #FFFFFF
primaryButtonBackground	`No`	Default: #000000
secondaryButtonColor	`No`	Default: #000000
secondaryButtonBackground	`No`	Default: #FFFFFF
textFieldBackground	`No`	Default: #F5F5F5
linkColor	`No`	Default: #0094FF
successColor	`No`	Default: #4CD964
borderColor	`No`	Default: #565656
dividerColor	`No`	Default: #EBEFF2
errorColor	`No`	Default: #FC2E01
borderRadius	`No`	Default: 12.0
displayStyle	`No`	`confirm`,`oneClick`. Default:`oneClick`.
paymentRetriesEnabled	`No`	If payment fails, whether the user can try again or return a failed result.

Payment

Wonder support 2 ways to make payment.

Field	Required	Description
amount	`Yes`	Order amount.
currency	`Yes`	Order currency.
orderNumber	`Yes`	Order number.
paymentMethod	`No`	Not needed when calling `present`; required when calling `pay`.
supportedPaymentModes	`No`	Supported payment modes. Available parameter: `preAuth`, `autoDebit`, `sale`.
lineItems	`No`	Order line item details.
status	`Output`	Available parameter: `completed`, `cancelled`, `failed`.
code	`Output`	If the payment goes wrong, an error code is returned.
message	`Output`	If the payment goes wrong, an error message is returned.

Present - Complete payment flow

Initialize a Payment Intent and complete payment immediately in one flow:

text


final intent = PaymentIntent(
    amount: 0.1,
    currency: "HKD",
    orderNumber: "202403081229292766405205",
  );

final result = await WonderPaymentPlugin.present(intent);

Select + pay — Alternative payment flow

2 steps for this flow are needed:

Step 1 - Select a payment method (no charge yet):

text

final intent = PaymentIntent(
    amount: 0.1,
    currency: "HKD",
    orderNumber: "202403081229292766405205",
  );

final method = await WonderPaymentPlugin.select(intent.transactionType);
intent.paymentMethod = method;

Step 2 - Start the payment:

final result = await WonderPaymentPlugin.pay(intent);

Preview — Preview payment method

View current payment methods and add a verified credit card.

text

WonderPaymentPlugin.preview()