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:

Stages a transaction via the backend API
Polls for status updates (configurable interval and timeout)
Returns a PaymentResult when the terminal reports approval, decline, or error
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

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

LittleFish Payments Cloud POS

Overview

Architecture

Components

Gateway

Models

Services

Presentation

Usage

Dependencies

Libraries

littlefish_payments_cloud_pos package

LittleFish Payments Cloud POS

Overview

Architecture

Components

Gateway

Models

Services

Presentation

Usage

Dependencies

Related

Libraries

littlefish_payments_cloud_pos package