iOS SDK | Wonder Developer Documentation

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

Workflow

Initiate the iOS 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 iOS SDK, Wechat Pay, Googl 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.

Podfile

Add the SDK dependency via CocoaPods.

Add the SDK dependency:

text

pod 'WonderPaymentSDK'

Or pin a specific version:

text

pod 'WonderPaymentSDK', 'x.x.x'

INFO

Replace x.x.x with the latest SDK version, then run pod install to install the SDK.

Info.plist

The following Info.plist entries handle two directions of app-to-app communication: URL types let payment apps return to your app, whitelist lets your app open payment apps, and AppDelegate receives the returned result. WeChat Pay requires an additional whitelist entry.

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>paydemo</string>
    </array>
  </dict>
</array>

INFO

paydemo 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.

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>

INFO

This is the opposite direction from URL types: whitelist lets your app open other apps, while URL types lets other apps return to yours.

WeChatPay dependency

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

text

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>weixin</string>
  <string>weixinULAPI</string>
  <string>weixinURLParamsAPI</string>
</array>

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.

iOS SDK configuration

The iOS 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

WonderPayment.initSDK(
  paymentConfig: PaymentConfig(
      appId: "f3615c8b-e402-48ac-bcd9-5af7a473ebdc",
      customerId: "87d8f5a5-e745-456d-938e-065bb77cedc7",
      fromscheme: "paydemo",
      // staging, alpha, production
      environment: .staging,
      /*
        public enum Locale: String {
          case zh_CN = "zh-CN", zh_HK = "zh-HK", en_US = "en-US"
        }
      */
      locale: .zh_HK,
      wechat: WechatConfig(
          appId: "wx5ac0eb5676b32e80",
          universalLink: "https://heypark.gobindo.com/"
      ),
      applePay: ApplePayConfig(
          merchantIdentifier: "merchant.app.wonder.hq.staging",
          merchantName: "Jek",
          countryCode: "HK"
      )
  ),
  uiConfig: UIConfig(
      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:`.staging`, `.alpha`,`.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.

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
textFieldBackground	`No`	Default: #F5F5F5
linkColor	`No`	Default: #0094FF
errorColor	`No`	Default: #FC2E01
successColor	`No`	Default: #4CD964
borderColor	`No`	Default: #565656
dividerColor	`No`	Default: #EBEFF2
borderRadius	`No`	Default: 12
displayStyle	`No`	`confirm`,`oneClick`. Default:`oneClick`.
showResult	`No`	Whether to show Wonder's pre-built result page. Default: `true`.

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

let paymentIntent = PaymentIntent(
  amount: 0.1, currency: "HKD", orderNumber: "202403081229292766405205"
)
WonderPayment.present(intent: paymentIntent) { result in
  print(result.status)
}

Select + pay — Alternative payment flow

2 steps for this flow are needed:

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

text

let paymentIntent = PaymentIntent(
    amount: 0.1,
    currency: "HKD",
    orderNumber: "202404181750209612110734"
)
let newIntent = paymentIntent.copy()
 WonderPayment.select(intent: paymentIntent) {
    method in
    newIntent.paymentMethod = method
}

Step 2 - Start the payment:

text

WonderPayment.pay(intent: newIntent) { result in
    print(result.status)
}

Preview — Preview payment method

View current payment methods and add a verified credit card.

text


WonderPayment.preview()