Flutter支付功能插件payment_flutter的使用

Flutter支付功能插件payment_flutter的使用

payment_flutter 是一个用于原生支付库（Android 和 iOS）的 Flutter 插件。

安装

添加依赖到 pubspec.yaml 文件

在你的 pubspec.yaml 文件中添加 payment_flutter 作为依赖项。

dependencies:
  payment_flutter: ^版本号

Android

打开项目中的 android 文件夹里的 Android Studio 项目。

1. 添加令牌以获取 Terra 库

在 local.properties 文件中添加 TekoGoogleRegistryToken。请联系 trung.cs@teko.vn 获取该令牌。

// android/local.properties
TekoGoogleRegistry.password=您的令牌

在项目的 build.gradle 文件（即 android/build.gradle）中添加以下代码：

// 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. 启用数据绑定和多 DEX 支持

在应用模块的 build.gradle 文件（即 android/app/build.gradle）中添加以下代码：

//...

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

//...

android {
  //...

  defaultConfig {
    //...

    multiDexEnabled true  // 添加此行
  }

  // 添加以下三行以启用数据绑定
  buildFeatures {
      dataBinding true
  }

  //...

}

3. 设置回调 URL 用于支付

支付完成后，银行应用或第三方支付应用将调用成功 URL 来通知支付结果。因此，需要配置回调 URL。

步骤 1：在 Terra 仪表板上设置支付服务

• 步骤 1：转到 Terra 项目
• 步骤 2：打开支付服务并添加回调 URL 到 callback.success 和 callback.cancel

步骤 2：配置 AndroidManifest.xml

• 步骤 1：转到项目中的 AndroidManifest.xml
• 步骤 2：添加以下意图过滤器来处理传入链接

//...
<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="您的域名" // 例如：payment.teko.vn
            android:path="您的路径" // 可选
            android:scheme="https" />
    </intent-filter>
</activity>
//...

注意： 确保 回调 URL 在 Terra 仪表板配置和 AndroidManifest.xml 中一致。

4. 如果应用使用 VNPay 电子钱包，则向应用模块添加 VNPay 电子钱包

请遵循以下页面的说明：https://demomb.vnpay.vn:20157/sdk/sdkwallet/index.html 如果有任何问题，请联系 Terra 团队。

注意： 目前，sdkwallet 只能在真实设备上运行。

iOS

打开项目中的 ios 文件夹里的 Xcode 项目。

1. 设置 GitHub 访问令牌以访问 Teko iOS 框架

请通过 trung.cs@teko.vn 联系获取令牌，并在计算机上添加新环境变量，键为 GITHUB_USER_TOKEN。

2. 设置 Podfile

步骤 1：定义源

在本地机器上：

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

在 CI 环境中：

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

步骤 2：配置目标框架

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # 设置有效架构
      config.build_settings['VALID_ARCHS'] = 'arm64 armv7 armv7s x86_64'

      # Xcode12 必须排除 arm64 作为模拟器架构
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"

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

正常情况下，Podfile 中有以下代码：

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

在这种情况下，我们更新现有代码：

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

    # 新代码
    target.build_configurations.each do |config|
      # 设置有效架构
      config.build_settings['VALID_ARCHS'] = 'arm64 armv7 armv7s x86_64'

      # Xcode12 必须排除 arm64 作为模拟器架构
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"

      config.build_settings["BUILD_LIBRARY_FOR_DISTRIBUTION"] = "YES"
    end
    # 结束新代码
  end
end

注意： 请不要将 <your_token_secret> 提交到 GitHub，否则它将被撤销。

3. 设置 URL 方案以处理结果

在 Info.plist 文件中添加 URL 方案：

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

4. 如果应用使用 VNPay 电子钱包，则向主包添加 VNPay 电子钱包

复制资源文件 VnpayWalletSDKBundleResouce.bundle（来自 https://demomb.vnpay.vn:20157/sdk/sdkwallet/index.html）到主包。

如有任何问题，请联系 Terra 团队。

注意： 目前，sdkwallet 只能在真实设备上运行。

库的使用

初始化/获取 TerraPayment 实例

静态方法：TerraPayment.getInstance(String appName) → Future<TerraPayment>

应在应用程序初始化阶段调用，并且必须在成功初始化 TerraApp 之后调用。

final terraPayment = await TerraPayment.getInstance(terraAppName);

切换商户配置

方法：TerraPayment.switchMerchantConfig(String merchantCode, String terminalCode) → Future<void>

final result = terraPayment.switchMerchantConfig("预期的商户代码", "预期的终端代码");

使用 TerraPayment 进行订单支付

方法：TerraPayment.payWith(PaymentUIRequest request) → Future<PaymentUIResult>

生成支付请求

打开可用方法屏幕

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

直接支付（无需可用方法屏幕）

final paymentRequestBuilder = PaymentUIRequestBuilder(Order(amount: 1000, orderCode: "order-code"))
    .setMainMethod(MainMethodVNPayGatewayQr(1000)) // 使用预期的方法，但不是 MainMethodAll
    .setExtraOptions(ExtraOptions(shouldShowPaymentResultScreen: true));

支持的支付方法包括：

• 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)

选择性地传递支付方法元数据

某些方法需要额外的配置才能进行支付。例如，使用 VNPayEWallet 时，必须传递元数据到 paymentRequestBuilder 之前调用 startUI。

paymentRequestBuilder.setMetadata(
    Metadata(
        vnPayEWallet: MetadataVnPayEWallet(
            partnerId: "0912345678", // 使用电话号码作为 partnerId，这是从 E-Wallet 团队推荐的
            phone: "0912345678",
            name: "Nguyen Van A",
            email: "a.nv@mail.com"
        ),
    ),
);

请求支付

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

switch (paymentResult.code) {
  case PaymentUIResultCode.success:
    // TODO
    break;
  case PaymentUIResultCode.failure:
    // TODO
    break;
  case PaymentUIResultCode.cancelled:
    // TODO: 可能忽略这种情况
    break;
}

打开 VNPay 电子钱包

方法：TerraPayment.openVnPayEWallet(VnPayEWalletUser user) → Future<void>

final eWalletUser = VnPayEWalletUser(
  partnerId: "0912345678", // 使用电话号码作为 partnerId，这是从 E-Wallet 团队推荐的
  phone: "0912345678",
  name: "Nguyen Van A",
  email: "a.nv@mail.com"
)

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

获取 VNPay 电子钱包用户信息

方法：TerraPayment.getVnPayEWalletUserInfo(String phone) → Future<VnPayEWalletUserInfoResult>

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

结果格式

{
  "code": "0", // 0 - 成功；-1 -> 用户未与电子钱包关联；其他错误：仅显示错误消息
  "desc": "成功", // 响应消息
  "data": {
    "kycStatus": "1", // 1 - KYC 已批准；0 - 未 KYC 或 KYC 未批准
    "balance": 20000.0, // 钱包余额
    "bankLinked": 0 // 1 - 已关联；0 - 尚未关联
  }
}

示例代码

import 'package:flutter/material.dart';

import 'package:payment_flutter_example/screens/home_screen.dart';

void main() {
  runApp(const MaterialApp(
    title: 'Payment Demo',
    home: HomeScreen(),
  ));
}