payment_flutter 0.1.0

A flutter plug-in for the native Payment library (Android and iOS).

payment_flutter

A flutter plug-in for the native Payment library (Android and iOS).

Installation

Add dependency to your pubspec.yaml file

Add payment_flutter as a dependency in your pubspec.yaml file.

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 [e-mail] 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.

1. 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
2. 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 [e-mail] to get the token

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

2. Set up the Podfile

1. 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'

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

Library usage

Initialize/get an TerraPayment instance

Static Method: TerraPayment.getInstance(String appName) → Future<TerraPayment>

Should be called in initialize phase of your app and must be called after initilizing TerraApp successful.

Switch payment config for merchants

Method: TerraPayment.switchMerchantConfig(String merchantCode, String terminalCode) → Future<void>

final terraPayment = await TerraPayment.getInstance(terraAppName);
final result = terraPayment.switchMerchantConfig("EXPECTED_MERCHANNT_CODE", "EXPECTED_TERMINAL_CODE");

Pay for an order with TerraPayment

Method: TerraPayment.payWith(PaymentUIRequest request) -> Future<PaymentUIResult>

Generate payment request

Open available methods screen

final paymentRequestBuilder = PaymentUIRequestBuilder(Order(amount: 1000, orderCode: "order-code"))
    .setMainMethod(MainMethodAll(1000))
    .setExtraOptions(ExtraOptions(shouldShowPaymentResultScreen: true));

Payment directly (without available methods screen)

final paymentRequestBuilder = PaymentUIRequestBuilder(Order(amount: 1000, orderCode: "order-code"))
    .setMainMethod(MainMethodVNPayGatewayQr(1000)) // use your expected method, but not MainMethodAll
    .setExtraOptions(ExtraOptions(shouldShowPaymentResultScreen: true));

Supported payment method:

• MainMethodAll(int amount)
• MainMethodVNPayGatewayQr(int amount)
• MainMethodVNPayGatewayAtm(int amount)
• MainMethodVNPayGatewayInternationalCard(int amount)
• MainMethodVNPayGatewayMobileBanking(int amount)
• MainMethodVNPayQrMms(int amount)
• MainMethodVNPayEWallet(int amount)
• MainMethodVNPayCustomer(int amount)
• MainMethodVNPaySposCard(int amount)
• MainMethodMomoGateway(int amount)
• MainMethodCod(int amount)
• MainMethodCash(int amount)
• MainMethodRefInput(int amount, string methodCode)
• MainMethodBankTransfer(int amount)
• MainMethodInstallment(int amount)

Payment methods metadata config(Optional)

There are some methods must add more config to payment, For example VNPayEWallet. So you must be passing metadata into paymentRequestBuilder before call startUI.

paymentRequestBuilder.setMetadata(
    Metadata(
        vnPayEWallet: MetadataVnPayEWallet(
            partnerId: "0912345678", // Use phone number for partnerId, this is a recommendation from the EWallet team
            phone: "0912345678",
            name: "Nguyen Van A",
            email: "[e-mail]"
        ),
    ),
);

Request payment

final terraPayment = await TerraPayment.getInstance(terraAppName);
final paymentResult = await terraPayment.payWith(paymentRequestBuilder.build());

switch (paymentResult.code) {
  case PaymentUIResultCode.success:
    // TODO
    break;
  case PaymentUIResultCode.failure:
    // TODO
    break;
  case PaymentUIResultCode.cancelled:
    // TODO: maybe ignore this case
    break;
}

Open VNPay e-wallet

Method: TerraPayment.openVnPayEWallet(VnPayEWalletUser user) -> Future<void>

final eWalletUser = VnPayEWalletUser(
  partnerId: "0912345678", // Use phone number for partnerId, this is a recommendation from the EWallet team
  phone: "0912345678",
  name: "Nguyen Van A",
  email: "[e-mail]"
)

final terraPayment = await TerraPayment.getInstance(terraAppName);
terraPayment.openVnPayEWallet(eWalletUser);

Get VNPay e-wallet user info

Method: TerraPayment.getVnPayEWalletUserInfo(String phone) -> Future<VnPayEWalletUserInfoResult>

final terraPayment = await TerraPayment.getInstance(terraAppName);
final result = await terraPayment.getVnPayEWalletUserInfo("0912345678");

Result format

{
  "code": "0", // 0 - Success; -1 => User has not linked with E-Wallet; Other errors: should only show error message
  "desc": "Success", // response message
  "data": {
    "kycStatus": "1", // 1 - kyc has been approved; 0 - not kyc or kyc has not been approved
    "balance": 20000.0, // balance of wallet
    "bankLinked": 0 // 1 - linked; 0 - not linked yet
  }
}