LittleFish Payments Cloud POS

Cloud POS payment gateway package for push-to-terminal card payments via the Cloud POS backend API.

Overview

This package provides a self-contained payment gateway (CloudPOSPaymentGateway) that extends PaymentGateway<CloudPosProvider> from littlefish_payments. It enables card-present transactions by staging payments on the backend API and polling for terminal completion, without requiring a direct connection between the mobile device and the POS terminal.

Architecture

Mobile App
  -> CloudPOSPaymentGateway (this package)
    -> CloudPosApiClient (HTTP)
      -> Cloud POS Backend API (littlefish.CloudPos service)
        -> Terminal Manager
          -> Physical POS Terminal

The gateway:

1. Stages a transaction via the backend API
2. Polls for status updates (configurable interval and timeout)
3. Returns a PaymentResult when the terminal reports approval, decline, or error
4. Automatically abandons transactions that exceed the local timeout

Components

Gateway

• CloudPOSPaymentGateway -- Extends PaymentGateway<CloudPosProvider>. Supports processPurchase, getTransactionInfo, and reversal. Exposes additional Cloud POS operations: retryTransaction, reassignTransaction.

Models

• CloudPosProvider -- Extends PaymentProvider with cloudPosApiBaseUrl for API routing.
• CloudPosTransaction -- Transaction model with status tracking and JSON serialization.
• CloudPosTerminal -- Terminal DTO with terminalId, displayName, isOnline.
• CloudPosTransactionStatus -- Enum with 8 states: staged, pendingOnTerminal, cardPresented, approved, declined, timedOut, error, abandoned. Includes isTerminal and isSuccessful helpers.

Services

• CloudPosApiClient -- HTTP client with 6 API methods: stageTransaction, pollTransactionStatus, reassignTransaction, retryTransaction, abandonTransaction, listTerminals.

Presentation

• CloudPosTerminalSelector -- Terminal picker widget with auto-selection for single-terminal merchants.
• CloudPosProgressView -- Transaction progress display showing current status during polling.

Usage

import 'package:littlefish_payments_cloud_pos/littlefish_payments_cloud_pos.dart';

// 1. Create provider settings
final provider = CloudPosProvider(
  cloudPosApiBaseUrl: 'https://api.example.com',
);

// 2. Create and initialise gateway
final gateway = CloudPOSPaymentGateway();
await gateway.initialise(settings: provider);

// 3. Process a payment
final result = await gateway.processPurchase(
  amount: Decimal.parse('100.00'),
  reference: 'INV-001',
);

Dependencies

• littlefish_payments ^8.1.3 -- Base gateway abstractions
• littlefish_core ^6.1.2 -- Core service interfaces
• littlefish_core_utils ^4.7.5 -- HTTP client utilities
• decimal ^3.2.4 -- Monetary arithmetic

Related

• Phase 1 (Backend): littlefish.CloudPos service in littlefish_core_api (PR #192)
• Implementation Plan: CPOS-PLAN_001 in littlefish_ai_planning