HpsClient class

Client for the local hobex Payment Service (HPS) REST API.

By default it talks to http://127.0.0.1:8080, which is correct when the app runs on the terminal itself. For remote testing from a dev machine, pass a baseUrl pointing at the terminal's IP, e.g. Uri.parse('http://192.168.0.187:8080').

The tid is normalized by the client itself: surrounding white space and leading zeros (e.g. 03600335) are stripped, so callers may pass the tid as printed on the terminal and the receipt. HPS only accepts it without the leading zero and answers anything else with 100108 "Invalid TID". A tid that is not made of digits only, or only of zeros, is passed on unchanged.

Constructors

HpsClient({Uri? baseUrl, required String tid, String defaultCurrency = 'EUR', String? defaultLanguage, Duration timeout = const Duration(minutes: 3), Client? httpClient, HpsObserver? observer})

Properties

baseUrl → Uri
Base URL of the HPS. Defaults to http://127.0.0.1:8080.
final
defaultCurrency → String
Currency used when a request does not specify one. Defaults to EUR.
final
defaultLanguage → String?
Terminal UI language (DE / IT / SI) used when not specified.
final
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
tid → String
Terminal identifier -- normalisiert (ohne fuehrende Null), siehe _normalizeTid.
final
timeout → Duration
Request timeout. Defaults to 3 minutes because card-present transactions block until the cardholder has interacted with the terminal.
final

Methods

abort({required String transactionId}) → Future<TransactionResponse>
Aborts an ongoing transaction, as long as it has not passed the point where the terminal can still take it back.
accountVerification({String? reference, String? transactionId, String? currency}) → Future<TransactionResponse>
Starts an account verification transaction (AVT) — a zero-amount check of the card.
batchTotals(DateTime since) → Future<Map<String, dynamic>>
Returns the batch totals (reconciliation sums) for the period starting at since.
cancel({required String transactionId, required num amount, String? currency, String? language, bool technicalCancel = false}) → Future<TransactionResponse>
Voids / cancels / reverses an existing transaction identified by transactionId. Must be activated by hobex.
close() → void
Gibt Ressourcen frei. Selbst erzeugte Verbindungen werden bereits pro Request geschlossen; ein injizierter Client gehoert dem Aufrufer und wird hier NICHT geschlossen. Bleibt aus API-Kompatibilitaet als sicherer No-op.
closeBatch(DateTime since) → Future<Map<String, dynamic>>
Closes the batch (end-of-day settlement) for the period starting at since. Returned as the raw decoded JSON (shape not in the REST PDF).
diagnosis() → Future<Diagnosis>
Reads the terminal diagnosis (device status, HPS version, host, …). This is a safe, non-financial health check.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
payment({required num amount, num? tip, String? forceTip, String? reference, String? transactionId, String? currency, String? language}) → Future<TransactionResponse>
Triggers a sale / purchase. The terminal prompts for a card and this call resolves once the card flow is complete.
preAuth({required num amount, String? reference, String? transactionId, String? currency, String? language}) → Future<TransactionResponse>
Triggers a pre-authorization (blocks an amount on the card). Must be activated by hobex.
preAuthCancel({required String preAuthTransactionId, required num amount, String? reference, String? currency}) → Future<TransactionResponse>
Cancels a former pre-authorization (releases the blocked amount). Must be activated by hobex.
preAuthCapture({required String preAuthTransactionId, required num amount, String? reference, String? currency, String? language}) → Future<TransactionResponse>
Captures a former pre-authorization identified by preAuthTransactionId. Must be activated by hobex.
refund({required num amount, String? originalTransactionId, String? reference, String? transactionId, String? currency, String? language}) → Future<TransactionResponse>
Triggers a refund (credit). Pass originalTransactionId for a referenced refund. Must be activated by hobex; the terminal asks for a password.
terminals() → Future<List<TerminalInfo>>
Lists the terminals known to this device: GET /api/terminals.
terminalStatus() → Future<bool>
Lightweight readiness check: GET /api/terminals/{tid}/status.
toString() → String
A string representation of this object.
inherited
transactionStatus({required String transactionId}) → Future<TransactionResponse>
Queries the status of a transaction (v2). Useful to recover the result after a connection dropped mid-payment.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

newTransactionId({int? nowMillis}) → String
Eine eindeutige, numerische Kennung mit hoechstens 18 Stellen: 13 Stellen Zeitstempel in Millisekunden, dazu ein 5-stelliger Zaehler je Millisekunde (statt Zufall). Der Zeitstempel allein reichte nicht -- zwei Vorgaenge in derselben Millisekunde bekamen dieselbe Kennung, und ein Zufallsanteil kann (selten, aber nachweislich geschehen) genauso kollidieren.