triPOS Mobile Flutter Plugin

基于 Worldpay triPOS Mobile SDK 的 Flutter 插件，支持通过 Ingenico 蓝牙读卡器进行移动支付，并支持 Android Moby 5500 USB 直连。

✨ 功能特性

功能	Android	iOS	说明
蓝牙扫描连接	✅	✅	设备扫描与连接
Moby 5500 USB 连接	✅	-	单台设备自动发现，无需蓝牙扫描
销售 (Sale)	✅	✅	刷卡/插卡/NFC 销售
退款 (Refund)	✅	✅	刷卡退款
关联退款	✅	✅	无需刷卡退款
作废 (Void)	✅	✅	取消已完成交易
预授权	✅	✅	冻结/完成/增量授权
Token 支付	✅	✅	无卡交易
离线模式 (S&F)	✅	✅	离线存储转发
自动恢复	✅	-	网络错误自动重置连接
蓝牙设备管理	✅	-	查询系统已连接蓝牙设备、按 MAC 解除配对

---

🚀 快速开始

import 'package:tripos_mobile/tripos_mobile.dart';

final tripos = TriposMobile();

// 1. 配置
final config = TriposConfiguration(
  hostConfiguration: HostConfiguration(
    acceptorId: 'your_acceptor_id',
    accountId: 'your_account_id',
    accountToken: 'your_account_token',
  ),
  deviceConfiguration: DeviceConfiguration(
    deviceType: DeviceType.ingenicoMoby5500,
  ),
);

// 2. 扫描设备
final devices = await tripos.scanBluetoothDevices(config);

// 3. 初始化连接
await tripos.initialize(config.copyWith(
  deviceConfiguration: config.deviceConfiguration.copyWith(
    identifier: devices.first,
  ),
));

// 4. 销售交易
final response = await tripos.processSale(
  SaleRequest(transactionAmount: 10.00),
);

if (response.isApproved) {
  print('交易成功! ID: ${response.host?.transactionId}, 批准号: ${response.host?.approvalNumber}');
}

Android Moby 5500 USB

USB 模式不调用 scanBluetoothDevices()。可以先检测物理连接，再由用户确认初始化：

final usbConfig = TriposConfiguration(
  hostConfiguration: HostConfiguration(
    acceptorId: 'your_acceptor_id',
    accountId: 'your_account_id',
    accountToken: 'your_account_token',
  ),
  deviceConfiguration: DeviceConfiguration(
    deviceType: DeviceType.ingenicoMoby5500,
    connectionType: DeviceConnectionType.usb,
    identifier: null,
  ),
);

final devices = await tripos.getConnectedUsbDevices();
if (devices.length == 1) {
  var device = devices.single;
  if (!device.hasPermission) {
    // 只申请 Android USB 权限，不连接或初始化 triPOS。
    device = await tripos.requestUsbDevicePermission(device.deviceId);
  }
  print('连接前读取的 USB 序列号: ${device.serialNumber}');
  await tripos.initialize(usbConfig);
}

tripos.usbDeviceEventStream.listen((event) async {
  if (event.type == UsbDeviceEventType.attached) {
    final device = event.device;
    if (device != null && !device.hasPermission) {
      final authorized = await tripos.requestUsbDevicePermission(
        device.deviceId,
      );
      print('连接前读取的 USB 序列号: ${authorized.serialNumber}');
    }
  }
});

requestUsbDevicePermission() 可能显示 Android 系统授权弹窗，但不会连接或初始化 triPOS。授权后可以在连接前读取设备公开的 USB 描述符序列号；部分固件可能不提供该字段，而且它不保证与 triPOS 连接回调中的业务序列号完全一致。

getConnectedUsbDevices() 和 usbDeviceEventStream 表示设备已物理插入，不代表 SDK 已可交易；仍需等待 initialize() 成功。USB 目前仅支持 Android Moby 5500，且一次连接一台设备。Android 设备必须支持 USB Host/OTG，并使用可传输数据的 USB 线。

---

📖 详细文档

文档	说明
安装配置	Android/iOS 配置、权限设置
配置说明	所有配置选项详解
基础交易	销售、退款、作废、预授权
Token 支付	Token 创建、销售、退款
离线存储转发	Store-and-Forward 功能
蓝牙设备管理	查询系统已连接蓝牙设备、按 MAC 解除配对
状态与事件	交易状态、设备事件监听
故障排除	常见问题及解决方案

---

📋 API 概览

核心方法

方法	说明
scanBluetoothDevices(config)	扫描附近的蓝牙支付设备
getConnectedUsbDevices()	初始化前查询已插入的 Moby 5500（Android）
requestUsbDevicePermission(deviceId)	初始化前申请 USB 权限并读取设备描述信息（Android）
initialize(config)	初始化 SDK 并连接设备
deinitialize()	断开设备并释放资源
cancelTransaction()	取消当前交易
getDeviceInfo()	获取已连接设备信息
getConnectedBluetoothDevices()	获取系统当前已连接蓝牙设备列表（Android）
unpairBluetoothDevice(macAddress)	按 MAC 地址解除蓝牙配对（Android）
isDeviceConnected()	检查设备当前连接状态
usbDeviceEventStream	监听 Moby 5500 USB 物理插拔（Android）

交易方法

方法	说明
processSale(request)	销售交易
processRefund(request)	退款交易 (需刷卡)
processLinkedRefund(request)	关联退款 (无需刷卡)
processVoid(request)	作废交易
processAuthorization(request)	预授权
processAuthorizationCompletion(request)	预授权完成
processIncrementalAuthorization(request)	增量授权
processReversal(request)	交易冲正

Token 方法

方法	说明
createToken(request)	刷卡创建 Token
createTokenWithTransactionId(request)	从交易 ID 创建 Token
processSaleWithToken(request)	Token 销售
processRefundWithToken(request)	Token 退款
processAuthorizationWithToken(request)	Token 预授权

离线交易方法

方法	说明
getAllStoredTransactions()	获取所有存储交易
getStoredTransactionsWithState(state)	按状态筛选存储交易
getStoredTransactionByTpId(tpId)	按 ID 获取存储交易
deleteStoredTransaction(tpId)	删除存储交易
manuallyForwardTransaction(request)	手动转发交易

事件流

流	说明
statusStream	交易状态更新 (Stream<VtpStatus>)
deviceEventStream	设备连接事件 (Stream<DeviceEvent>)

---

📱 支持的设备

• Ingenico Moby 5500（Android 支持 Bluetooth 和 USB；iOS 支持 Bluetooth）
• Ingenico Moby 8500
• Lane 3000/5000/7000/8000

Android triPOS Mobile SDK 4.7.0 已移除 BBPOS 2XBT/3XBT 支持。Dart 里的旧枚举仅用于源码兼容，不应再用于 Android 初始化。

---

💡 示例应用

查看 example/lib/main.dart 获取完整示例。

cd example
flutter run

---

📄 许可证

本插件基于 Worldpay triPOS Mobile SDK 开发，使用需遵守 Worldpay 许可协议。

🤝 贡献

欢迎提交 Issue 和 Pull Request！