TransactionResponse class

Result of a transaction request (payment, refund, pre-auth, capture, void, AVT) or of a transaction-status (v2) query.

A response object is returned even when a payment is declined: declines are signalled in the body, not by an exception. Exceptions are only thrown for HTTP/transport errors.

Careful — responseCode != "0" is NOT the test for a decline. That reading is what caused the double charge of 2026-08-24: noStatementCode (9027) is a code other than "0" and yet says nothing at all — it stands for "still running" just as much as for "aborted" or "never seen". Reading it as a decline reports "nothing was charged, safe to retry" for a payment that is running right now.

A decline is a conclusive code other than "0". Use isConclusive to ask whether this response settles anything, and only then isApproved to ask which way; isNoStatement names the gap. A response that is not conclusive is a reason to keep clarifying, never an outcome.

Zweite Lehre, am 27.08.2026: isConclusive darf keine Negativliste sein, die sich als Positivliste ausgibt. Bis dahin galt "jeder Code ausser null und noStatementCode ist schluessig" -- das unterstellt, wir kennten bereits alle Codes, die KEINE Aussage sind. Gemessen an einem hobex-HPS (TID 3600335, HPS 1.10.0, Firmware 7.3.6): die Statusabfrage antwortete auf eine nicht rein numerische Kennung mit einem bis dahin unbenannten Code, technicalErrorCode (9900, "Technical Error Database") -- ueber die alte Regel schluessig, und der Klaerweg machte daraus declined fuer einen Vorgang, unter dem tatsaechlich Geld geflossen sein kann. Jetzt gilt die Umkehrung: isConclusive ist wahr nur fuer einen Code, dessen Bedeutung GEMESSEN und hier BENANNT ist. Jeder andere -- ob er wie ein Fehlercode aussieht oder nicht, ob er neu ist oder schlicht nie gemessen wurde -- ist eine Wissensluecke, siehe isUnknownCode.

Constructors

TransactionResponse({required Map<String, dynamic> raw, String? transactionId, String? originalTransactionId, String? tid, String? receipt, String? approvalCode, String? reference, String? transactionDate, String? cardNumber, String? cardExpiry, String? brand, String? cardIssuer, String? transactionType, String? currency, num? amount, num? tip, String? responseCode, String? responseText, Cvm? cvm, String? bin, String? statusCode, String? statusText, String? state, bool? cleared, String? source, String? approvalDate, String? actionCode, String? aid, String? vu}): const
TransactionResponse.fromJson(Map<String, dynamic> json): factory

Properties

actionCode → String?: Action code. Status v2 only.
final
aid → String?: EMV Application Identifier. Status v2 only.
final
amount → num?: Transaction amount.
final
approvalCode → String?: Authorization / approval code.
final
approvalDate → String?: Approval date. Status v2 only.
final
bin → String?: BIN — the first 6 digits of the PAN.
final
brand → String?: Card brand, e.g. Visa, MasterCard, Maestro.
final
cardExpiry → String?: Card expiry, format YYMM.
final
cardIssuer → String?: Card issuer.
final
cardNumber → String?: Masked card number (PAN).
final
cleared → bool?: Whether the transaction has already been cleared. Status v2 only.
final
codeInfo → HpsCode?: Der Eintrag dieses Codes in HpsCodes.all, oder null, wenn seine Bedeutung nicht feststeht bzw. kein Code vorliegt.
no setter
currency → String?: Currency (ISO 4217 alpha), e.g. EUR.
final
cvm → Cvm?: Cardholder verification method.
final
hashCode → int: The hash code for this object.
no setterinherited
isApproved → bool: true when the transaction was approved (responseCode == "0").
no setter
isCanceled → bool: true, wenn der Vorgang aufgehoben wurde (transactionCanceledCode).
no setter
isConclusive → bool: true, wenn diese Antwort ueberhaupt eine Aussage ueber den Ausgang traegt -- also einen Ergebniscode nennt, dessen Bedeutung feststeht und der in HpsCodes.all als HpsCodeEffect.conclusive gefuehrt wird.
no setter
isConclusiveAsStatus → bool: Wie isConclusive, aber fuer die Antwort auf eine STATUSABFRAGE: ein Code, der die Anfrage selbst abweist (HpsCode.rejectsRequest, etwa 100022 "Terminal is blocked" oder 100108 "Invalid TID"), sagt dort nichts ueber den gesuchten Vorgang -- nur, dass diese Abfrage nicht bedient wurde. Als declined gelesen, hiesse ein gesperrtes Terminal "die Zahlung ist nicht belastet".
no setter
isHostUncertain → bool: true, wenn der Code einen Ausgang meldet, den das Terminal selbst nicht kennt: der hobex-Host war beteiligt, und das Terminal storniert nicht von sich aus (siehe HpsCodeEffect.hostUncertain).
no setter
isInProgress → bool: true when a status query reports the transaction is still running (responseCode == null).
no setter
isInvalid → bool: true, wenn das Terminal den Vorgang als ungueltig abgewiesen hat (invalidTransactionCode) -- eine positive Aussage: nichts geschehen.
no setter
isNoStatement → bool: true, wenn das Terminal zu dieser Kennung keine Auskunft gibt (noStatementCode).
no setter
isNotAbortable → bool: true, wenn ein HpsClient.abort daran scheiterte, dass der Vorgang nicht mehr abbrechbar war (notAbortableCode).
no setter
isTechnicalError → bool: true, wenn das Terminal einen technischen Fehler meldet (technicalErrorCode) -- gemessen im Zusammenhang mit einer nicht rein numerischen Kennung, nachdem die Karte bereits verarbeitet war. Seit der TECS-Liste (16.09.2026) als Backend-Fehler eingeordnet, also isHostUncertain: ob belastet wurde, ist offen.
no setter
isUnknownCode → bool: true, wenn ein Ergebniscode VORHANDEN ist, dessen Bedeutung aber nicht feststeht -- er fehlt in HpsCodes.all.
no setter
needsReversal → bool: true, wenn zu diesem Code ein Storno nachzuschicken ist (HpsCode.sendReversal) -- der Host hat nicht oder nicht brauchbar geantwortet, etwa 9908.
no setter
originalTransactionId → String?: Identifier of the original transaction (for capture / refund / void).
final
raw → Map<String, dynamic>: The raw decoded JSON, for fields not modelled explicitly.
final
reason → HpsCodeReason?: Worauf eine Kasse bei dieser Antwort reagiert -- null ohne Code, HpsCodeReason.unknown fuer einen Code ausserhalb der Tabelle.
no setter
receipt → String?: Receipt number.
final
reference → String?: Reference echoed from the request (null if none was sent).
final
responseCode → String?: Response code. "0" means approved. null (status v2 only) means the transaction is still in progress — see isInProgress. An empty string from the terminal is normalised to null by fromJson: an empty code carries no more information than a missing one, and treating it as a real (non-"0") code would misreport an unresolved outcome as declined.
final
responseText → String?: Human readable response text.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
source → String?: What triggered the transaction, e.g. API, ECR. Status v2 only.
final
state → String?: Transaction state, e.g. OK, VOID, FAILED. Status v2 only.
final
statusCode → String?: Mapped status code (from HOC). Status v2 only.
final
statusText → String?: Mapped status text (from HOC). Status v2 only.
final
tid → String?: Terminal identifier.
final
tip → num?: Tip amount.
final
transactionDate → String?: Transaction date/time as returned by the terminal.
final
transactionId → String?: Unique transaction identifier (echoed / generated). Store this to later void or query the transaction.
final
transactionType → String?: Transaction type, e.g. SELL, PREAUTH, CAPTURE, VOID, REFUND.
final
vu → String?: Merchant id (Vertragsunternehmen). Status v2 only.
final

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
override

Operators

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

Constants

abortedCode → const String: Ergebniscode 100002 ("Aborted"): der Zahlungs- oder Gutschriftvorgang wurde abgebrochen, bevor er zu Ende gefuehrt wurde.
amountOutOfRangeCode → const String: Ergebniscode 100019 ("Amount is not in a valid range"): der Betrag liegt ausserhalb des zulaessigen Bereichs.
appSelectFailedCode → const String: 100005 "App select failed": Anwendungsauswahl gescheitert -- nichts belastet. Im Betrieb am 28.08.2026 gesehen, damals ungedeutet.
badRequestCode → const String: 100001 "Bad Request": fehlerhafte Anfrage der Kasse -- nichts belastet.
cardDeclinedCode → const String: 100015 "Card declined": vom EMV-Kernel abgelehnt, vor dem Host -- nichts belastet. Im Betrieb am 28. und 31.08.2026 gesehen, damals ungedeutet.
cardInfoNotEnteredCode → const String: 100014 "Card information wasn't entered" (MOTO) -- nichts belastet.
cardNotPresentCode → const String: Ergebniscode 100003 ("Card not present"): die Karte wurde nicht aufgelegt.
cardNotSupportedCode → const String: 100017 "Card Not Supported" -- nichts belastet.
cardReadFailedCode → const String: 100004 "Card read failed": Karte nicht lesbar -- nichts belastet. Im Betrieb am 28.08.2026 gesehen (TID 3556988), damals ungedeutet.
chipDataMismatchCode → const String: 100026 "Transaction was declined." (Chip-Daten fuer eine Karte ohne Chip) -- Ausgang ungewiss, siehe isHostUncertain.
completionFailedCode → const String: 100024 "Transaction completion has failed" -- Ausgang ungewiss, siehe isHostUncertain.
diagnosisFailedCode → const String: 100013 "Diagnosis failed" -- nichts belastet.
hostCommunicationFailedCode → const String: 100006 "Communication with TecsXml failed" (No auto-reversal) -- Ausgang ungewiss, siehe isHostUncertain.
hostStepFailedCode → const String: 100007 "Processing of TecsXml step failed" (No auto-reversal) -- Ausgang ungewiss, siehe isHostUncertain.
hostTimeoutReversedCode → const String: 100029 "Communication with TecsXml timeout" (auto-reversal): das Terminal storniert selbst -- nichts belastet.
internalErrorCode → const String: 100999 "Internal Error": Sammelcode -- Ausgang ungewiss, siehe isHostUncertain.
invalidAmountCode → const String: Ergebniscode 9003 ("Invalid Amount"): das Terminal weist den Betrag ab, BEVOR es die Karte anfordert.
invalidMessageTypeCode → const String: 100023 "Invalid message type": ungueltige Host-Antwort -- Ausgang ungewiss, siehe isHostUncertain.
invalidTidCode → const String: Ergebniscode 100108 ("Invalid TID"): die uebergebene Terminal-Kennung gibt es an diesem Geraet nicht.
invalidTidDocumentedCode → const String: 100008 "Invalid TID" laut hobex. Am Geraet gemessen wurde fuer dieselbe Lage invalidTidCode (100108); beide gelten.
invalidTransactionCode → const String: Ergebniscode 9002 ("Invalid Transaction"): das Terminal hat den Vorgang als UNGUELTIG abgewiesen -- eine positive Aussage, dass nichts geschehen ist.
invalidTxTypeCode → const String: 100009 "Invalid Tx Type": Vorgangstyp unbekannt -- nichts belastet.
maxRetriesExceededCode → const String: 100012 "Max retries exceeded": zu viele Kartenversuche -- nichts belastet.
noStatementCode → const String: Ergebniscode 9027 ("Original Tx not found"): das Terminal hat geantwortet, sagt zu dieser Kennung aber NICHTS aus.
notAbortableCode → const String: Ergebniscode 100010: der Vorgang ist NICHT MEHR ABBRECHBAR.
notFoundCode → const String: 100011 "Not Found": keine Aussage ueber den Vorgang, siehe isNoStatement fuer den Unterschied zu 9027.
passwordNotEnteredCode → const String: 100021 "Failed to enter the password" -- nichts ausgezahlt.
refundDisabledCode → const String: 100025 "Refund transactions are disabled" -- nichts ausgezahlt.
refundPasswordInvalidCode → const String: 100020 "Refund password is invalid" -- nichts ausgezahlt.
scepEnrollmentFailedCode → const String: 100018 "Scep enrollment failed" -- nichts belastet.
technicalErrorCode → const String: Ergebniscode 9900 ("Technical Error Database").
terminalBlockedCode → const String: 100022 "Terminal is blocked": nicht IN_OPERATION -- nichts belastet.
terminalBusyCode → const String: 100998 "Terminal is busy" -- die Anfrage wurde nicht angenommen. Als HTTP-Status gemessen: 409, siehe HpsHttpException.isTerminalBusy.
tipSelectionFailedCode → const String: 100028 "Tip selection process has failed." -- nichts belastet.
transactionCanceledCode → const String: Ergebniscode 9011 ("Transaction Canceled"): der Vorgang unter dieser Kennung wurde aufgehoben.
unsupportedUserDataCode → const String: 100027 "Unsupported UserData in TecsXml Response" -- Ausgang ungewiss, siehe isHostUncertain.
wrongPinCode → const String: Ergebniscode 55 ("PIN falsch"): der Host hat die Autorisierung abgelehnt, weil die eingegebene PIN falsch war -- nichts belastet.