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: a leading zero (e.g. 03600335) is stripped, so callers may pass the tid as printed on the terminal without worrying about the format HPS expects.

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 setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

tid → String

Terminal identifier — normalisiert (ohne fuehrende Null).

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.