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 must be given without a leading zero (e.g. 3600335, not 03600335).

Constructors

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

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 — without leading zero.

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<String?>

Aborts an ongoing transaction before a card has been tapped. Returns the transaction id of the aborted transaction, if provided.

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, bool technicalCancel = false}) → Future<TransactionResponse>

Voids / cancels / reverses an existing transaction identified by transactionId. Must be activated by hobex.

close() → void

Releases the underlying HTTP client (only if it was created internally).

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.

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