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
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
originalTransactionIdfor 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.