hobex_hps library

hobex Payment Service (HPS) — typed client for the terminal's local REST API (http://127.0.0.1:8080 when the app runs on the terminal).

Bewusst getrennt vom alten, cloud-basierten Hobex (KasseneckApi.hobexPay / hobexRefund, die ueber Kasseneck-Cloud-Endpunkte gehen). Eigener Import, damit alt und neu sauber nebeneinander leben:

import 'package:kasseneck_api/hobex_hps.dart';

final payments = HpsPayments(HpsClient(tid: '3600335'));
final res = await payments.pay(
  amount: 1.00,
  transactionId: HpsClient.newTransactionId(),
);
// res.outcome: approved | declined | unresolved
// Geldregel: nur declined heisst "nichts belastet, Wiederholung
// gefahrlos". unresolved darf NIE erneut belastet werden -- warnen und
// ueber res.transactionId klaeren.

Fuer eine Zahlung immer HpsPayments, nicht HpsClient.payment direkt: dort steht die Kennung erst mit der Antwort fest, und isApproved == false wirft "abgelehnt" mit "laeuft noch" in einen Topf. Genau daraus entstand am 24.08.2026 eine Doppelbelastung. HpsClient bleibt oeffentlich fuer alles Uebrige (Diagnose, Batch, Statusabfrage).

Classes

Diagnosis
Result of GET /api/terminals/{tid}/diagnosis — a health snapshot of the terminal and its connection to the hobex host.
DiscoveredHpsTerminal
Ein gefundenes Terminal: Adresse plus die Kennungen, die es selbst nennt.
HobexReceipt
HpsClient
Client for the local hobex Payment Service (HPS) REST API.
HpsCode
Ein Ergebniscode, dessen Bedeutung feststeht.
HpsCodes
Die Tabelle selbst und die Abfrage darauf.
HpsDiscoveryResult
Ergebnis der Suche: Treffer plus die abgesuchten Netze.
HpsEvent
Ein Ereignis im Zahlweg. Bewusst schlank und ohne Kartendaten -- was hier hineingegeben wird, landet im Protokoll der App.
HpsPayments
Kartenzahlung, deren Ausgang immer bekannt ist.
HpsResult
Ergebnis eines Zahlvorgangs samt Kennung und Klaerungsverlauf.
LocalIpv4
Eine IPv4-Adresse dieses Geraets auf einer Schnittstelle.
ScannedHpsSubnet
Ein abgesuchtes Netz -- fuer die Anzeige in der Kasse und die Fehlersuche.
TerminalInfo
A terminal entry returned by GET /api/terminals.
TransactionResponse
Result of a transaction request (payment, refund, pre-auth, capture, void, AVT) or of a transaction-status (v2) query.

Enums

CardPaymentOutcome
Ausgang eines Kartenzahlvorgangs -- die einzige Frage, die der Aufrufer wirklich hat: darf ich es nochmal versuchen?
Cvm
Cardholder Verification Method.
HpsCodeEffect
Wie ein Ergebniscode den Ausgang eines Vorgangs bestimmt.
HpsCodeReason
Worauf eine Kasse reagiert -- der Grund hinter einem Ergebniscode.
HpsCodeSource
Woher die Bedeutung eines Codes stammt.
HpsEventKind
Art eines Ereignisses im Zahlweg.
HpsTransactionType
Numeric transaction type as sent in the request body of the /api/transaction/payment route.

Constants

hpsDefaultPort → const int
Standard-Port der HPS-Schnittstelle am Terminal.
hpsScanBudget → const Duration
Zeitbudget der ganzen Suche, ueber alle Netze zusammen.

Functions

discoverHpsTerminals({int port = hpsDefaultPort, Duration budget = hpsScanBudget, Duration probeTimeout = hpsProbeTimeout, Duration verifyTimeout = hpsVerifyTimeout, int concurrency = hpsScanConcurrency, bool stopAtFirst = false, Future<List<LocalIpv4>> interfaces()?, HpsTcpProbe probe = hpsTcpReachable, Client? httpClient}) → Future<HpsDiscoveryResult>
Sucht hobex-HPS-Terminals im lokalen Netz.

Typedefs

HpsObserver = void Function(HpsEvent event)
Empfaenger der Ereignisse. Die App legt ihn typischerweise auf ihr Absturzprotokoll.

Exceptions / Errors

HpsConnectionException
Thrown when the HPS could not be reached at all (socket error, timeout, connection refused, …).
HpsException
Base class for all errors thrown by this package.
HpsHttpException
Thrown when the HPS responds with a non-2xx HTTP status code.