Flutter支付终端插件stripe_terminal的使用

stripe_terminal 是一个用于扫描 Stripe 读卡器并连接到它们以获取支付方法的 Flutter 插件。本文将介绍如何在 Flutter 应用中使用该插件。

安装

Android

无需配置，开箱即用。

iOS

需要在 Info.plist 文件中提供权限请求字符串，并授权后台模式。

示例内容：

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location access is required in order to accept payments.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth access is required in order to connect to supported bluetooth card readers.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to supported card readers.</string>

后台模式授权：

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

使用

初始化 SDK

首先需要初始化 SDK 并获取连接令牌。

import 'package:stripe_terminal/stripe_terminal.dart';

StripeTerminal stripeTerminal = StripeTerminal(
  fetchToken: () async {
    // 调用后端 API 获取连接令牌
    const token = "pst_test_XXXXXXXXXX...."; 
    return token;
  },
);

示例后端代码（Node.js）

import Stripe from "stripe";
import express from "express";

const stripe = new Stripe("sk_test_XXXXXXXXXXXXXXXXXX", {
  apiVersion: "2020-08-27"
});

const app = express();

app.get("/connectionToken", async (req, res) => {
  const token = await stripe.terminal.connectionTokens.create();
  res.send({
    success: true,
    data: token.secret
  });
});

app.post("/createPaymentIntent", async (req, res) => {
  const pi = await stripe.paymentIntents.create({
    amount: 1000,
    currency: "USD",
    capture_method: "manual",
    payment_method_types: ["card_present"]
  });

  res.send({
    success: true,
    paymentIntent: pi
  });
});

app.listen(8000, () => {
  console.log("Server started");
});

发现附近的设备并展示给用户

stripeTerminal
  .discoverReaders(simulated: true)
  .listen((List<StripeReader> readers) {
    setState(() {
      this.readers = readers;
    });
  });

连接到蓝牙读卡器

bool connected = await stripeTerminal.connectBluetoothReader(readers[0].serialNumber);
if (connected) {
  print("Connected to a device");
}

扫描卡片

stripeTerminal
  .readReusableCardDetail()
  .then((StripePaymentMethod paymentMethod) {
    print("A card was read, the last four digit is ${paymentMethod.card?.last4}");
  });

扫描支付方式

Future<String> createPaymentIntent() async {
  Response invoice = await _dio.post("/createPaymentIntent");
  return invoice.data["paymentIntent"]["client_secret"];
}

String payment_intent_client_secret = await createPaymentIntent();

stripeTerminal
  .collectPaymentMethod(payment_intent_client_secret)
  .then((StripePaymentIntent paymentIntent) {
    print("A payment intent has captured a payment method, send this payment intent to your backend to capture the payment");
  });

目前支持的功能

• 初始化终端 SDK
• 扫描读卡器
• 连接到设备（仅限 Android 上的蓝牙设备）
• 检查连接状态
• 检查已连接的设备
• 从设备读取支付方式

缺少的功能

• 创建支付意图
• 处理支付
• 捕获支付

示例 Demo

以下是一个完整的示例代码，展示了如何使用 stripe_terminal 插件：

import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:stripe_terminal/stripe_terminal.dart';

void main() {
  runApp(const MaterialApp(home: MyApp()));
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  [@override](/user/override)
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final Dio _dio = Dio(BaseOptions(baseUrl: "YOUR_BACKEND_URL"));

  Future<String> getConnectionString() async {
    Response response = await _dio.get("/connectionToken");
    if (!(response.data["success"])) {
      throw Exception("Failed to get connection token because ${response.data["message"]}");
    }
    return (response.data)["data"];
  }

  Future<void> _pushLogs(StripeLog log) async {
    debugPrint(log.code);
    debugPrint(log.message);
  }

  Future<String> createPaymentIntent() async {
    Response invoice = await _dio.post("/createPaymentIntent");
    return invoice.data['data']["client_secret"];
  }

  late StripeTerminal stripeTerminal;

  [@override](/user/override)
  void initState() {
    super.initState();
    _initStripe();
  }

  _initStripe() async {
    stripeTerminal = await StripeTerminal.getInstance(fetchToken: getConnectionString);
    stripeTerminal.onNativeLogs.listen(_pushLogs);
  }

  bool simulated = true;
  StreamSubscription? _sub;
  List<StripeReader>? readers;
  String? paymentIntentId;

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Plugin example app')),
      body: Center(
        child: Column(
          children: [
            ListTile(
              onTap: () {
                setState(() {
                  simulated = !simulated;
                  _initStripe();
                });
              },
              title: const Text("Scanning mode"),
              trailing: Text(simulated ? "Simulator" : "Real"),
            ),
            ListTile(
              onTap: () async {
                await Permission.bluetooth.request();
                await Permission.bluetoothScan.request();
                await Permission.bluetoothConnect.request();
              },
              title: const Text("Ask Bluetooth Permission"),
            ),
            TextButton(child: const Text("Init Stripe"), onPressed: _initStripe),
            TextButton(
              child: const Text("Get Connection Token"),
              onPressed: () async {
                String connectionToken = await getConnectionString();
                _showSnackbar(connectionToken);
              },
            ),
            if (_sub == null)
              TextButton(
                child: const Text("Scan Devices"),
                onPressed: () async {
                  setState(() {
                    readers = [];
                  });
                  _sub = stripeTerminal
                      .discoverReaders(DiscoverConfig(discoveryMethod: DiscoveryMethod.bluetooth, simulated: simulated))
                      .listen((readers) {
                    setState(() {
                      this.readers = readers;
                    });
                  });
                },
              ),
            if (_sub != null)
              TextButton(
                child: const Text("Stop Scanning"),
                onPressed: () async {
                  setState(() {
                    _sub?.cancel();
                    _sub = null;
                  });
                },
              ),
            TextButton(
              child: const Text("Connection Status"),
              onPressed: () async {
                stripeTerminal.connectionStatus().then((status) {
                  _showSnackbar("Connection status: ${status.toString()}");
                });
              },
            ),
            TextButton(
              child: const Text("Connected Device"),
              onPressed: () async {
                stripeTerminal.fetchConnectedReader().then((StripeReader? reader) {
                  _showSnackbar("Connected Device: ${reader?.toJson()}");
                });
              },
            ),
            if (readers != null)
              ...readers!.map(
                (e) => ListTile(
                  title: Text(e.serialNumber),
                  trailing: Text(describeEnum(e.batteryStatus)),
                  leading: Text(e.locationId ?? "No Location Id"),
                  onTap: () async {
                    await stripeTerminal.connectBluetoothReader(e.serialNumber, locationId: "your_location_id").then((value) {
                      _showSnackbar("Connected to a device");
                    }).catchError((e) {
                      if (e is PlatformException) {
                        _showSnackbar(e.message ?? e.code);
                      }
                    });
                  },
                  subtitle: Text(describeEnum(e.deviceType)),
                ),
              ),
            TextButton(
              child: const Text("Read Reusable Card Detail"),
              onPressed: () async {
                stripeTerminal.readReusableCardDetail().then((StripePaymentMethod paymentMethod) {
                  _showSnackbar("A card was read: ${paymentMethod.card?.toJson()}");
                });
              },
            ),
            TextButton(
              child: const Text("Collect Payment Method"),
              onPressed: () async {
                paymentIntentId = await createPaymentIntent();
                stripeTerminal.collectPaymentMethod(paymentIntentId!).then((StripePaymentIntent paymentIntent) async {
                  _dio.post("/confirmPaymentIntent", data: {"paymentIntentId": paymentIntent.id});
                  _showSnackbar("A payment method was captured");
                });
              },
            ),
          ],
        ),
      ),
    );
  }

  _showSnackbar(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        behavior: SnackBarBehavior.floating,
        content: Text(message, style: const TextStyle(color: Colors.red)),
      ),
    );
  }
}