Stripe Terminal

Log in to dashboard.stripe.com and navigate to Terminal → Get started. If you haven't registered a reader location yet, create one (Terminal → Locations → + New location). Each physical reader must be assigned to a Stripe Terminal location. From the Terminal hardware shop (hardware.stripe.com), order a reader compatible with your use case. The BBPOS WisePad 3 connects over Bluetooth and is the most common choice for mobile POS on iOS and Android. The Stripe Reader S700 is a smart reader with a built-in touchscreen, better for semi-fixed countertop setups. Both accept chip, tap, and swipe. Note your reader's serial number — you'll pair it in a later step. Also navigate to Developers → API keys and securely copy your secret key (sk_test_* for development, sk_live_* for production). This key will go only into your backend proxy — not into FlutterFlow.

Stripe Terminal's SDK requires a fresh connection token before it can communicate with any reader. The SDK calls a token-provider function you supply during initialization — this function must call POST https://api.stripe.com/v1/terminal/connection_tokens using your secret key and return the token string. Because the secret key must never be in the Flutter app, you deploy this as a Firebase Cloud Function or Supabase Edge Function. For Firebase (Node.js): create a function that receives a POST request from the app, calls the Stripe connection_tokens endpoint with your sk_* key from environment config, and returns { secret: token.secret }. Register the function's URL in your FlutterFlow project as a Dart constant (not in an API Call group — you'll pass it directly into the Terminal SDK initialization in the Custom Action). For Supabase (Deno): create an Edge Function at supabase/functions/connection-token/index.ts that does the same thing, deployed with supabase functions deploy connection-token and the secret set via supabase secrets set STRIPE_SECRET_KEY=sk_xxx. The URL pattern will be https://yourproject.supabase.co/functions/v1/connection-token.

1// Firebase Cloud Function: connection token endpoint (Node.js)
2const functions = require('firebase-functions');
3const stripe = require('stripe')(functions.config().stripe.secret_key);
4const cors = require('cors')({ origin: true });
5
6exports.connectionToken = functions.https.onRequest((req, res) => {
7  cors(req, res, async () => {
8    try {
9      const token = await stripe.terminal.connectionTokens.create();
10      res.json({ secret: token.secret });
11    } catch (err) {
12      res.status(500).json({ error: err.message });
13    }
14  });
15});
16
17// Deploy with:
18// firebase functions:config:set stripe.secret_key="sk_test_xxx"
19// firebase deploy --only functions:connectionToken

In FlutterFlow, go to Custom Code in the left navigation panel → + Add → Action. Name the action first one TerminalInit. Before writing any Dart, click into the Dependencies field and type stripe_terminal, select the package (use version ^2.1.0 or later — verify the current stable version on pub.dev before adding). FlutterFlow will automatically add this to the generated pubspec.yaml when building. The stripe_terminal SDK communicates with physical readers over Bluetooth LE, which on iOS requires both Bluetooth and Location permissions (iOS requires location access for Bluetooth LE scanner). On Android, Bluetooth and location runtime permissions are needed. In FlutterFlow, go to Settings → App Details → Permissions (iOS) and enable 'Bluetooth Always' and 'Location When In Use' — add descriptive usage strings like 'This app uses Bluetooth to connect to your card reader' and 'Location is needed to discover nearby card readers'. For Android, go to Settings → App Details → Permissions (Android) and enable Bluetooth, Bluetooth Scan, Bluetooth Connect, and Access Fine Location. Missing even one of these strings causes reader discovery to return zero results with no error message in the console — it's the silent failure that trips up almost every first-time Terminal developer.

1// Verify exact version on pub.dev before adding:
2// https://pub.dev/packages/stripe_terminal
3// Package name to add in FlutterFlow Custom Code → Dependencies:
4// stripe_terminal
5//
6// Also add this guard at the top of every Terminal Custom Action:
7import 'package:flutter/foundation.dart' show kIsWeb;
8
9if (kIsWeb) {
10  // Terminal is not supported on web
11  // Show a user-friendly message or return early
12  return;
13}

You need four Dart Custom Actions that mirror the Terminal SDK's state machine. Create each under Custom Code → + Add → Action. Action 1 — TerminalInit: initialize the Terminal SDK with your connection-token provider URL. The SDK calls this URL every time it needs a fresh token. Action 2 — DiscoverReaders: call Terminal.instance.discoverReaders() with your desired discovery method (bluetoothScan or bluetoothProximity for WisePad 3). Collect the list of discovered readers into an App State variable (List of String, containing reader serial numbers or display names) and show them in a FlutterFlow ListView. Action 3 — ConnectReader: accept a reader serial from the list, call Terminal.instance.connectBluetoothReader() with that reader and a locationId (the Stripe Terminal location ID you created). Store the connected reader state in an App State variable. Action 4 — CollectAndProcessPayment: create a PaymentIntent amount (in cents), call Terminal.instance.collectPaymentMethod(), then Terminal.instance.processPayment(). On success, extract the PaymentIntent ID from the result and write it to Firestore or Supabase as a confirmed transaction. Wire these four actions to buttons in a FlutterFlow POS screen: 'Search for Readers' → DiscoverReaders, reader list item tap → ConnectReader, 'Charge Card' button → CollectAndProcessPayment. Use App State boolean variables (isConnecting, isProcessing) to show loading spinners while each step runs.

1// Action 1: TerminalInit
2import 'package:flutter/foundation.dart' show kIsWeb;
3import 'package:stripe_terminal/stripe_terminal.dart';
4
5Future terminalInit(String connectionTokenUrl) async {
6  if (kIsWeb) return;
7  await StripeTerminal.instance.init(
8    fetchToken: () async {
9      final response = await http.post(Uri.parse(connectionTokenUrl));
10      final body = jsonDecode(response.body);
11      return body['secret'] as String;
12    },
13  );
14}
15
16// Action 4: CollectAndProcessPayment
17import 'package:stripe_terminal/stripe_terminal.dart';
18
19Future<String> collectAndProcessPayment(int amountInCents) async {
20  if (kIsWeb) return '';
21  // Create PaymentIntent on Stripe via your backend, then collect
22  final paymentIntent = await StripeTerminal.instance.createPaymentIntent(
23    CreatePaymentIntentParameters(
24      amount: amountInCents,
25      currency: 'usd',
26      paymentMethodTypes: [PaymentMethodType.cardPresent],
27    ),
28  );
29  final collected = await StripeTerminal.instance
30      .collectPaymentMethod(paymentIntent.id);
31  final processed = await StripeTerminal.instance.processPayment(collected.id);
32  return processed.id; // PaymentIntent ID
33}

Because the Terminal Custom Actions use native Bluetooth APIs, you must test on a physical iOS or Android device — the FlutterFlow canvas preview, Run Mode, and web exports will not execute these actions. Use FlutterFlow's 'Test on Device' feature (top right → Test on Device → scan QR with your device) or export the Flutter project and run it from your IDE. Pair your reader with the Stripe test environment first: in the Stripe Dashboard (test mode), go to Terminal → Readers and register your reader's serial number to your test location. Use Stripe's test card 4242 4242 4242 4242 in test mode — your physical WisePad 3 or S700 will accept it without charging real money. Watch your App State variables in FlutterFlow's Debug Mode panel to trace each step. Common edge cases to handle: (a) reader goes to sleep after ~2 minutes of inactivity — add a 'Reconnect Reader' button that calls ConnectReader again; (b) payment collection is cancelled by the customer (card removed) — wrap collectPaymentMethod in a try/catch and surface an error state in App State; (c) network loss mid-payment — the SDK holds the payment method data locally until connectivity is restored, but surface a 'No internet' warning to the operator. If you'd rather skip building the permission configuration and error-state management yourself, RapidDev's team builds FlutterFlow Terminal integrations like this every week — free scoping call at rapidevelopers.com/contact.