Getting Started

Requirement#

Application has been integrated with Terra. If not, please follow this Terra integration instruction.

Installation#

Firstly please refer to Teko repository access guide for instruction to setup the environment.

When the environment is ready, add the below code to import:

iOS
Android
Flutter

Flutter side#

flutter pub add payment_flutter

For detail installation, please refer Payment installation

Android#

Open the android project inside the android folder of your project in Android studio.

1. Add token to get Terra libraries#

Add TekoGoogleRegistryToken to the local.properties file (contact trung.cs@teko.vn to get the token).

// android/local.properties

TekoGoogleRegistry.password=<your-token>

In project build.grade (android/build.gralde file). Add the following code:

// android/build.gradle
allprojects {
    repositories {
        ...

        Properties properties = new Properties()
        properties.load(project.rootProject.file('local.properties').newDataInputStream())

        maven {
            setUrl("https://asia-southeast1-maven.pkg.dev/teko-development/teko-mobile-sdks")

            authentication {
                basic(BasicAuthentication)
            }

            credentials {
                username = "_json_key_base64"
                password = properties.getProperty('TekoGoogleRegistry.password')
            }
        }
    }
}

2. Enable dataBinding and multiDex for the app module#

Add some line below to the build.gradle of app module (android/app/build.gradle file).

//...

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
// add line below
apply plugin: 'kotlin-kapt'

//...

android {
  //...

  defaultConfig {
    //...

    multiDexEnabled true  // Add this line
  }

  // Add 3 lines below to enable dataBinding
  buildFeatures {
      dataBinding true
  }

  //...

}

3. Set up callback urls for payment#

After payment through banks app or payment app's 3rd, these app will call the success url to inform the result to Payment SDK. In this case we need the application to config the callback urls.

Set up Payment service on Terra Dashboard
- Step 1: Go to your project on terra
- Step 2: Open Payment Service and add your urls callback into callback.success and callback.cancel
Set up AndroidManifest file.
- Step 1: Go to AndroidManifest in your project.
- Step 2: Add intent filters for incoming links as below.

//...
<activity android:name="vn.teko.android.payment.ui.PaymentActivity">
    <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="your_domain" // for ex: payment.teko.vn
            android:path="your_path" // optional
            android:scheme="https" />
    </intent-filter>
</activity>
//...

Notes: Make sure the urls callback is same between Payment service on Terra config and AndroidManifest.

4. Add VNPay e-wallet to app module (if your app uses VNPay e-wallet)#

Please follow the instruction in this page: https://demomb.vnpay.vn:20157/sdk/sdkwallet/index.html. Please contact Terra team if you have any concerns.

Note: Currently, sdkwallet only runs on real device.

iOS#

Open the ios project insdie the android folder of your project in xcode.

1. Setup github access token for accessing Teko iOS frameworks#

Please contact trung.cs@teko.vn to get the token

Add new environment variable to your computer with the following key: GITHUB_USER_TOKEN.

2. Set up the Podfile#

At the beginning of your Podfile, define the source:

// on local machine
source 'https://github.com/teko-vn/Specs-ios.git'

// on CI environment
source 'https://' + ENV['GITHUB_USER_TOKEN'] + '@github.com/teko-vn/Specs-ios.git'

Configure targets for frameworks

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # set valid architecture
      config.build_settings['VALID_ARCHS'] = 'arm64 armv7 armv7s x86_64'

      # Xcode12 have to exclude arm64 for simulator architecture
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"

      config.build_settings["BUILD_LIBRARY_FOR_DISTRIBUTION"] = "YES"
    end
  end
end

Normally, in the Podfile there is the following code:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
  end
end

In this case, we update the existing code to:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)

    # new code
    target.build_configurations.each do |config|
      # set valid architecture
      config.build_settings['VALID_ARCHS'] = 'arm64 armv7 armv7s x86_64'

      # Xcode12 have to exclude arm64 for simulator architecture
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"

      config.build_settings["BUILD_LIBRARY_FOR_DISTRIBUTION"] = "YES"
    end
    # end of new code
  end
end

Note: please do not commit <your_token_secret> to github or it will be revoked

4. Set up callback urls for payment#

Add URL Schemes for handle result. App scheme must match callbackURL field value in Terra dashboard.

    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>app.sheme</string>
            </array>
        </dict>
    </array>

3. Add UINavigation to your iOS app#

Open the AppDelegate.swift file.

// AppDelegate.swift

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        GeneratedPluginRegistrant.register(with: self)

        // Begin of adding a new UINavigationController
        let controller = window?.rootViewController as! FlutterViewController

        // create and then add a new UINavigationController
        let navigationController = UINavigationController(rootViewController: controller)
        self.window.rootViewController = navigationController
        navigationController.setNavigationBarHidden(true, animated: false)
        self.window.makeKeyAndVisible()
        // End of adding a new UINavigationController

        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

4. Add VNPay e-wallet to main bundle (if your app uses VNPay e-wallet)#

Copy bundle resource VnpayWalletSDKBundleResouce.bundle (in this page) to main bundle.

Please contact Terra team if you have any concerns.

Note: Currently, sdkwallet only runs on real device.

Using CocoaPods

Add MinervaUI pod to your Podfile

pod 'MinervaUI', '~> [version]'

Add URL Schemes for handle result. App scheme must match callbackURL field value in Terra dashboard.

    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>app.sheme</string>
            </array>
        </dict>
    </array>

Using Gradle

In build.gradle app level (usually app/build.gradle).

dependencies {
    implementation("vn.teko.android.payment:payment-ui:$version")
}

After payment through banks app or payment app's 3rd, It will be call success url as inform result to Payment Service. In that case we expected the main app(applied PaymentSDK) will be show as default after that. That's why we need config deep link callback.

Setup Payment serviceon Terra Dashboard
- Step1: Go to your project on terra
- Step2: Open Payment Service and add your urls callback into callback.success and callback.cancel
Setup in AndroidManifest
- Step1: Go to AndroidManifest(app) in your project
- Step2 : Add intent filters for incoming links as below

 ....
  <activity android:name="vn.teko.android.payment.ui.PaymentActivity">
            <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="your_domain" // for ex: payment.teko.vn
                    android:path="your_path" // optional
                    android:scheme="https" />
            </intent-filter>
   </activity>

...

Notes: Make sure the urls callback is same between Payment service on Terra config and AndroidManifest

Dependency#

iOS
Android
Flutter