Building a Terminal App with Flutter

Your Flutter app sits between the cashier and your backend. It never touches Paystack APIs directly.

Frontend (Flutter): Displays the product catalog, lets the cashier build orders, shows the payment status, and triggers charge requests.

Backend (Node.js/Express): Stores products, orders, and terminal assignments. Calls the Paystack Terminal API to push payments. Receives webhooks and pushes status updates to the Flutter app.

Why not call Paystack from Flutter? The Terminal API requires your secret key. Secret keys must never exist in frontend code, mobile or web. Your backend is the only component that holds the secret key and makes Paystack API calls.

The Flutter app communicates with your backend over HTTP. For real-time updates (payment status changes), use Server-Sent Events (SSE) or periodic polling. WebSockets are another option but add complexity.

Organize your Flutter project around features, not layers.

// Flutter project structure
// lib/
//   main.dart
//   models/
//     product.dart
//     order.dart
//     terminal_status.dart
//   services/
//     api_service.dart        // HTTP calls to your backend
//     terminal_service.dart   // Terminal-specific API calls
//   providers/
//     order_provider.dart     // Order state management
//     terminal_provider.dart  // Terminal state management
//   screens/
//     pos_screen.dart         // Main POS interface
//     payment_screen.dart     // Payment status screen
//     settings_screen.dart    // Terminal selection, config
//   widgets/
//     product_grid.dart
//     order_summary.dart
//     payment_status_card.dart

models/ define your data structures. services/ handle HTTP communication. providers/ manage state. screens/ are full-page views. widgets/ are reusable components.

The API service handles all communication with your backend. Here is the core structure in Dart-like pseudocode that maps to your Node.js backend endpoints.

// The Flutter app calls your backend like this:
// POST /api/orders - create an order
// POST /api/terminal/charge - push payment to terminal
// GET  /api/terminal/:id/status - check terminal state
// GET  /api/orders/:id - get order details

// Your backend (Node.js) handles these and calls Paystack Terminal API:
// api-service.js (backend)
var express = require('express');
var router = express.Router();

router.post('/api/orders', async function(req, res) {
  var items = req.body.items;
  var terminalId = req.body.terminal_id;

  var total = items.reduce(function(sum, item) {
    return sum + (item.price * item.quantity);
  }, 0);

  var order = await db.query(
    'INSERT INTO orders (items, total_amount, terminal_id, status) ' +
    'VALUES ($1, $2, $3, $4) RETURNING *',
    [JSON.stringify(items), total, terminalId, 'draft']
  );

  return res.json(order.rows[0]);
});

router.post('/api/terminal/charge', async function(req, res) {
  var orderId = req.body.order_id;
  var result = await chargeOrderAtTerminal(orderId);
  return res.json(result);
});

router.get('/api/terminal/:id/status', async function(req, res) {
  var state = await getTerminalState(req.params.id);
  return res.json(state);
});

The Flutter app makes HTTP calls to these endpoints. It receives JSON responses and updates the UI accordingly.

The terminal can be in several states. Your state management needs to track the current state and update the UI reactively.

// terminal-state-backend.js
// Backend endpoint that Flutter polls for status
router.get('/api/terminal/:id/payment-status/:reference', async function(req, res) {
  var reference = req.params.reference;

  var payment = await db.query(
    'SELECT status, amount, completed_at FROM terminal_transactions WHERE reference = $1',
    [reference]
  );

  if (payment.rows.length === 0) {
    return res.json({ status: 'unknown' });
  }

  return res.json(payment.rows[0]);
});

// Flutter polls this endpoint every 2 seconds while waiting for payment
// States the Flutter app tracks:
// - idle: terminal ready for new payment
// - pushing: sending payment request to terminal
// - waiting_for_card: terminal displaying amount, waiting for customer
// - processing: card presented, payment being processed
// - success: payment completed
// - failed: payment declined or error
// - timeout: no response within the timeout window

Polling interval. Poll every 2 seconds while a payment is active. Stop polling once you get a terminal status (success, failed, or timeout). Do not poll when the terminal is idle.

Optimistic UI. When the cashier taps "Charge," immediately show "Sending to terminal..." without waiting for the API response. Update based on what comes back. This makes the app feel responsive.

POS apps live on tablets, not phones. Design for a landscape orientation on a 10-inch screen.

Split view layout. Left side: product catalog as a grid of large, tappable cards. Right side: current order summary with item list, quantities, and total. Bottom right: "Charge" button, large and prominent.

Minimum touch target: 56x56 logical pixels. Cashiers tap quickly and sometimes inaccurately. Make buttons big. Product cards should be at least 100x100 pixels.

Visual feedback on every tap. Ripple effects, color changes, haptic feedback. The cashier needs to know their tap registered, especially in a noisy environment.

Status colours. Use consistent colours for payment states: blue for waiting, green for success, red for failure, yellow for warning. The cashier should be able to read the status from across the counter.

Keep it simple. A POS screen should have no more than 3 to 5 actions visible at any time. Hide advanced features (reports, settings, refunds) behind a menu. The main screen is for building orders and charging customers.

Internet connectivity in African retail environments is not guaranteed. Build your Flutter app to handle interruptions.

Cache the product catalog. Store products locally using SQLite or Hive. The cashier can build orders without internet. When connectivity returns, sync any pending orders to the backend.

Queue payment requests. If the network is down when the cashier taps "Charge," queue the payment locally. Show "Payment will be sent when internet is available." Process the queue when connectivity returns.

Show connectivity status. Display a small indicator (green dot for online, red dot for offline) in the app bar. The cashier should always know whether the app is connected.

// connectivity-check.js (backend health endpoint)
router.get('/api/health', function(req, res) {
  return res.json({ status: 'ok', timestamp: Date.now() });
});

// The Flutter app pings this endpoint every 10 seconds
// If it fails 3 times in a row, show the offline indicator

Do not allow charges when offline. Even though you can queue the request, the terminal needs internet to process card payments. Tell the cashier: "Terminal payments require internet. Accept cash or wait for connectivity."

Test at three levels: unit tests for business logic, widget tests for UI, and integration tests for the full flow.

Mock the backend. Your Flutter tests should not hit your real backend. Use a mock HTTP client that returns predefined responses for each endpoint. This lets you test every state transition without a running server.

Test every payment state. Simulate success, failure, timeout, and network error. Verify the UI shows the correct message and buttons for each state.

Test on a real tablet. Emulators do not replicate the feel of tapping a physical screen. Test on an actual 10-inch tablet to verify touch targets, scroll behaviour, and readability.

Test with a real terminal. Before going live, test the full flow with a physical Paystack Terminal device and test cards. Verify that the Flutter app shows the correct status at each stage.

For broader testing strategies, see the complete testing guide.