hobex_hps 0.1.0

Dart & Flutter client for the hobex Payment Service (HPS) local REST API: card payments, refunds, pre-auth and voids on hobex / Sunmi card terminals.

hobex_hps

Dart & Flutter client for the hobex Payment Service (HPS) local REST API.
Card payments, refunds, pre-auth, voids and diagnosis on hobex / Sunmi card terminals — no SDK lock-in.

Unofficial. This is an independent, community-maintained client and is not affiliated with, endorsed by, or supported by hobex. "hobex" is a trademark of its respective owner.

The hobex Payment Service (HPS) runs directly on the payment terminal (e.g. a Sunmi device with the hobex Android system) and exposes a plain JSON API on http://localhost:8080 without authentication. hobex_hps wraps that API in a small, typed, dependency-light Dart client: card payments, refunds, pre-authorizations, captures, voids, account verification, transaction status and terminal diagnosis — ideal for POS / cash-register (Kassensystem) apps built with Dart or Flutter.

Features

• 💳 Sale, pre-authorization, capture, pre-auth cancel
• ↩️ Refund (incl. referenced refund), void / reversal, abort
• 🔎 Transaction status (v2), batch totals / close, terminal diagnosis
• 🧾 Fully typed response (approvalCode, masked PAN, brand, CVM, receipt no. …) plus the raw JSON
• 🪶 Pure Dart, a single dependency (http), usable in any Flutter app
• ✅ Declines are normal results — not thrown exceptions

Install

dependencies:
  hobex_hps: ^0.1.0

Quick start

import 'package:hobex_hps/hobex_hps.dart';

// On the terminal the default base URL (http://127.0.0.1:8080) is correct.
final hps = HpsClient(tid: '3600335'); // ⚠️ TID without leading zero

// Safe, non-financial health check.
final diag = await hps.diagnosis();
print(diag); // deviceStatus=IN_OPERATION, hps=1.8.4, test=true ...

// A €1.00 sale — the terminal prompts for a card and this awaits the flow.
final res = await hps.payment(amount: 1.00, reference: 'order-42');
if (res.isApproved) {
  print('OK ${res.brand} ${res.cardNumber}  approval=${res.approvalCode}');
} else {
  print('Declined: ${res.responseCode} ${res.responseText}');
}

hps.close();

Operations

Method	HPS endpoint
payment(amount:)	POST /api/transaction/payment (type 1)
preAuth(amount:)	POST /api/transaction/preauth
preAuthCapture(preAuthTransactionId:, amount:)	POST /api/transaction/preauthcapture
preAuthCancel(preAuthTransactionId:, amount:)	DELETE /api/transaction/preauth
refund(amount:, originalTransactionId:)	POST /api/transaction/refund
cancel(transactionId:)	DELETE /api/transaction/payment/{tid}/{txId}
abort(transactionId:)	POST /api/transaction/abort/{tid}/{txId}
accountVerification()	POST /api/transaction/avt/
transactionStatus(transactionId:)	GET /api/v2/transactions/{tid}/{txId}
diagnosis()	GET /api/terminals/{tid}/diagnosis
batchTotals(since)	GET /api/terminals/{tid}/batchtotal/{dateTime}
closeBatch(since)	GET /api/terminals/{tid}/closebatch/{dateTime}

Notes

• TID without leading zero — e.g. 3600335, not 03600335.
• On-device the app calls localhost:8080; that address never changes even though the device's LAN IP (DHCP) might.
• Amounts are major units (1.50 = €1,50).
• A declined payment is returned as a TransactionResponse with isApproved == false. Exceptions (HpsHttpException, HpsConnectionException) are only thrown for HTTP/transport errors.
• responseCode == "0" means approved.
• Refund / void / pre-auth must be activated by hobex for the account (otherwise the HPS returns 403).

Maintainer

Built and maintained by Kreiseck – Software Solutions — a software studio from Salzburg, Austria, focused on custom POS / cash-register (Kassensystem) software, mobile apps and payment-terminal integrations.

License

MIT © Ali Aktas Kreiseck – Software Solutions. See LICENSE.