@kreiseck/kasseneck-api 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,38 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 0.7.2
+
+### `55` („PIN falsch") ist eine gemessene Host-Ablehnung → `declined`
+
+**Anlass:** Vorfall vom 02.09.2026 am Produktivterminal 3556988 (HPS 1.11.4,
+Firmware 2.3.9), vom Dart-Zwilling `kasseneck_api` 6.4.0 übernommen — die
+erste echte Host-Ablehnung, die je beobachtet wurde. Die Zahlung antwortete
+direkt mit `55`, die Statusabfrage danach elfmal in Folge ebenfalls. Als
+Wissenslücke kostete der Code 90 s Klärung ins Budget, `unresolved`, einen
+stehenden Merker und eine Rückfrage an den Bediener — für eine falsch
+getippte PIN.
+
+- Neu: `WRONG_PIN_CODE`, in `HPS_MEASURED_CODES` als schlüssig geführt.
+- Bewusst **keine** Familienregel für zweistellige Host-Codes: ISO 8583 führt
+  dort auch Genehmigungen (`08`, `10`, `11`, `85`). Die Zwei-`9027`-Regel
+  greift bei Host-Codes nicht (der Status antwortet mit dem Code selbst);
+  ungemessene Host-Codes enden weiterhin bei `unresolved`.
+- `fixtures/hobex-hps-codes.json` neu erzeugt; die Vertragsdatei nennt jetzt
+  unter `ergaenztAn`, welcher Code von welchem Gerät stammt.
+
+### Neu: `HpsPaymentResult.lastResponse` und Terminal-Klartext im Nachweis
+
+Am 02.09.2026 sah der Bediener bei einer Antwort `55` „PIN falsch" nur
+„Ausgang unklar", musste raten und buchte die abgelehnte Zahlung als bezahlt;
+75 EUR Umsatz waren weg. Der Klartext hätte die Entscheidung getragen.
+
+- `lastResponse`: die letzte Terminal-Antwort bei `unresolved`, auch wenn sie
+  nichts entschied — Material für Anzeige und Katalog, nie ein Beleg.
+  `response` bleibt bei `unresolved` weiterhin ungesetzt.
+- Der Nachweis nennt bei einem unbekannten Code den Klartext des Terminals:
+  `Terminal nennt einen unbekannten Code (55) "PIN falsch"`.
+
 ## 0.7.0
 
 ### Neu: Unterpfad `./partner` — die Partner-API

package/dist/cjs/payments/hobex-hps/index.d.ts

@@ -23,5 +23,5 @@ export { type HpsPaymentEvent, type HpsPaymentEventKind, type HpsPaymentObserver
 export { type CardPaymentOutcome, type HpsPaymentResult, mayRetrySafely, } from './outcome.js';
 export { type HpsCancelOptions, type HpsPaymentOptions, type HpsPayments, type HpsPaymentsOptions, type HpsRefundOptions, createHpsPayments, } from './payments.js';
 export { MAX_TRANSACTION_ID_LENGTH, createHpsTransactionIdGenerator, isValidHpsTransactionId, newHpsTransactionId, type HpsTransactionIdGeneratorOptions, } from './transaction-id.js';
-export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, type HpsMeasuredCode, type HpsTransactionResponse, } from './transaction-response.js';
+export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, WRONG_PIN_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, type HpsMeasuredCode, type HpsTransactionResponse, } from './transaction-response.js';
 export { hobexReceiptFromHps } from './receipt.js';

package/dist/cjs/payments/hobex-hps/index.js

@@ -19,7 +19,7 @@
  * des Aufrufers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hobexReceiptFromHps = exports.parseHpsTransactionResponse = exports.isUnknownCode = exports.isTechnicalError = exports.isNotAbortable = exports.isNoStatement = exports.isInProgress = exports.isConclusive = exports.isCanceled = exports.isApproved = exports.TRANSACTION_CANCELED_CODE = exports.TERMINAL_BUSY_HTTP_STATUS = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.INVALID_TRANSACTION_CODE = exports.HPS_MEASURED_CODES = exports.CARD_NOT_PRESENT_CODE = exports.APPROVED_CODE = exports.ABORTED_CODE = exports.newHpsTransactionId = exports.isValidHpsTransactionId = exports.createHpsTransactionIdGenerator = exports.MAX_TRANSACTION_ID_LENGTH = exports.createHpsPayments = exports.mayRetrySafely = exports.PREFLIGHT_CONNECT_CODES = exports.HpsTransactionIdError = exports.HpsPreflightError = exports.HpsConnectTransportError = exports.HpsConnectTerminalError = exports.HpsConnectException = exports.HpsClarifyTimeoutError = exports.createHpsConnectClient = void 0;
+exports.hobexReceiptFromHps = exports.parseHpsTransactionResponse = exports.isUnknownCode = exports.isTechnicalError = exports.isNotAbortable = exports.isNoStatement = exports.isInProgress = exports.isConclusive = exports.isCanceled = exports.isApproved = exports.TRANSACTION_CANCELED_CODE = exports.TERMINAL_BUSY_HTTP_STATUS = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.WRONG_PIN_CODE = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.INVALID_TRANSACTION_CODE = exports.HPS_MEASURED_CODES = exports.CARD_NOT_PRESENT_CODE = exports.APPROVED_CODE = exports.ABORTED_CODE = exports.newHpsTransactionId = exports.isValidHpsTransactionId = exports.createHpsTransactionIdGenerator = exports.MAX_TRANSACTION_ID_LENGTH = exports.createHpsPayments = exports.mayRetrySafely = exports.PREFLIGHT_CONNECT_CODES = exports.HpsTransactionIdError = exports.HpsPreflightError = exports.HpsConnectTransportError = exports.HpsConnectTerminalError = exports.HpsConnectException = exports.HpsClarifyTimeoutError = exports.createHpsConnectClient = void 0;
 var connect_client_js_1 = require("./connect-client.js");
 Object.defineProperty(exports, "createHpsConnectClient", { enumerable: true, get: function () { return connect_client_js_1.createHpsConnectClient; } });
 var errors_js_1 = require("./errors.js");
@@ -49,6 +49,7 @@ Object.defineProperty(exports, "NOT_ABORTABLE_CODE", { enumerable: true, get: fu
 Object.defineProperty(exports, "INVALID_AMOUNT_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_AMOUNT_CODE; } });
 Object.defineProperty(exports, "AMOUNT_OUT_OF_RANGE_CODE", { enumerable: true, get: function () { return transaction_response_js_1.AMOUNT_OUT_OF_RANGE_CODE; } });
 Object.defineProperty(exports, "INVALID_TID_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_TID_CODE; } });
+Object.defineProperty(exports, "WRONG_PIN_CODE", { enumerable: true, get: function () { return transaction_response_js_1.WRONG_PIN_CODE; } });
 Object.defineProperty(exports, "NO_STATEMENT_CODE", { enumerable: true, get: function () { return transaction_response_js_1.NO_STATEMENT_CODE; } });
 Object.defineProperty(exports, "TECHNICAL_ERROR_CODE", { enumerable: true, get: function () { return transaction_response_js_1.TECHNICAL_ERROR_CODE; } });
 Object.defineProperty(exports, "TERMINAL_BUSY_HTTP_STATUS", { enumerable: true, get: function () { return transaction_response_js_1.TERMINAL_BUSY_HTTP_STATUS; } });

package/dist/cjs/payments/hobex-hps/outcome.d.ts

@@ -18,8 +18,23 @@ export type CardPaymentOutcome = 'approved' | 'declined' | 'unresolved';
 export interface HpsPaymentResult {
     readonly outcome: CardPaymentOutcome;
     readonly transactionId: string;
-    /** Die letzte Antwort des Terminals, sofern eine schluessige ankam. */
+    /**
+     * Die Antwort des Terminals, die den Ausgang FESTGESCHRIEBEN hat -- nur
+     * bei `approved` und `declined`. Bei `unresolved` fehlt sie: eine
+     * Nicht-Aussage darf nicht als Beleg mitgegeben werden. Was das Terminal
+     * zuletzt gesagt hat, steht dann in [lastResponse].
+     */
     readonly response?: HpsTransactionResponse;
+    /**
+     * Die letzte Antwort des Terminals bei `unresolved`, sofern ueberhaupt
+     * eine ankam -- auch wenn sie nichts entschied (9027, 9900, ein
+     * unbekannter Code). NIE ein Beleg, sondern Material fuer Anzeige und
+     * Katalog: am 02.09.2026 sah der Bediener bei einer Antwort `55`
+     * "PIN falsch" nur "Ausgang unklar", musste raten und buchte eine
+     * abgelehnte Zahlung als bezahlt. Der Klartext des Terminals haette die
+     * Entscheidung getragen. Bei schluessigem Ausgang nicht gesetzt.
+     */
+    readonly lastResponse?: HpsTransactionResponse;
     /**
      * Verlauf der Klaerung, in Reihenfolge — der Nachweis, der im
      * Belastungsstreit gelesen wird. Behauptet nie eine Ursache, die nicht

package/dist/cjs/payments/hobex-hps/payments.js

@@ -70,7 +70,7 @@ function createHpsPayments(client, target, options = {}) {
             return `Antwort mit technischem Fehler (${transaction_response_js_1.TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang, Ausgang wird geklaert`;
         }
         if ((0, transaction_response_js_1.isUnknownCode)(res)) {
-            return `Terminal nennt einen unbekannten Code (${res.responseCode}) -- Ausgang wird geklaert`;
+            return `Terminal nennt einen unbekannten Code (${res.responseCode})${klartext(res)} -- Ausgang wird geklaert`;
         }
         return `Antwort ohne Aussage (${res.responseCode}) -- Ausgang wird geklaert`;
     }
@@ -83,10 +83,21 @@ function createHpsPayments(client, target, options = {}) {
             return `Status: technischer Fehler (${transaction_response_js_1.TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang`;
         }
         if ((0, transaction_response_js_1.isUnknownCode)(status)) {
-            return `Status: unbekannter Code (${status.responseCode}) -- keine Aussage`;
+            return `Status: unbekannter Code (${status.responseCode})${klartext(status)} -- keine Aussage`;
         }
         return null;
     }
+    /**
+     * Der Klartext des Terminals zu einem UNBEKANNTEN Code, als Zusatz fuer den
+     * Nachweis -- oder leer, wenn keiner mitkam. Nur hier, nicht bei den
+     * gemessenen Codes: deren Bedeutung ist benannt. Bei einem unbekannten Code
+     * ist er dagegen das Einzige, was ein Mensch lesen kann -- "PIN falsch"
+     * neben `55` haette am 02.09.2026 gereicht, um nicht "bezahlt" zu buchen.
+     */
+    function klartext(res) {
+        const text = res.responseText?.trim();
+        return text ? ` "${text}"` : '';
+    }
     /** Ordnet eine Terminal-Antwort ein. `null`, wenn sie nichts entscheidet. */
     function fromResponse(res, id, steps) {
         if (!(0, transaction_response_js_1.isConclusive)(res))
@@ -188,9 +199,19 @@ function createHpsPayments(client, target, options = {}) {
         }
         return null;
     }
-    function open(id, steps) {
+    /**
+     * [letzteAntwort] ist die letzte Antwort, die das Terminal in dieser
+     * Klaerung gab -- als `lastResponse` fuer Anzeige und Katalog,
+     * ausdruecklich NICHT als `response`.
+     */
+    function open(id, steps, letzteAntwort) {
         emit('resolved', steps[steps.length - 1], id);
-        return { outcome: 'unresolved', transactionId: id, steps: [...steps] };
+        return {
+            outcome: 'unresolved',
+            transactionId: id,
+            ...(letzteAntwort ? { lastResponse: letzteAntwort } : {}),
+            steps: [...steps],
+        };
     }
     /**
      * Fuehrt [call] aus, aber hoechstens so lange, wie vom [resolveBudgetMs]
@@ -263,7 +284,7 @@ function createHpsPayments(client, target, options = {}) {
      * [NO_STATEMENT_CODE] (`9027`) beim Pollen einen Aussagewert, den es sonst
      * nicht hat. Siehe [ausGeschlossenerAntwort].
      */
-    async function resolve(id, steps, antwortMitCode = false) {
+    async function resolve(id, steps, antwortMitCode = false, letzteAntwort) {
         emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
         const start = now();
         const elapsedMs = () => now() - start;
@@ -284,6 +305,7 @@ function createHpsPayments(client, target, options = {}) {
             try {
                 status = await withinBudget(elapsedMs, () => client.status({ ...target, transactionId: id }));
                 transportFailures = 0;
+                letzteAntwort = status;
             }
             catch (e) {
                 transportFailures += 1;
@@ -312,7 +334,7 @@ function createHpsPayments(client, target, options = {}) {
             wait = nextWait(wait);
         }
         steps.push('Ausgang bleibt offen');
-        return open(id, steps);
+        return open(id, steps, letzteAntwort);
     }
     /**
      * Liest `9027` beim Pollen als "nicht genehmigt" -- aber NUR, wenn das
@@ -372,7 +394,7 @@ function createHpsPayments(client, target, options = {}) {
      * Budget, Backoff und Transportfehler-Deckelung sind unveraendert aus
      * [resolve] uebernommen.
      */
-    async function resolveCancel(id, steps) {
+    async function resolveCancel(id, steps, letzteAntwort) {
         emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
         const start = now();
         const elapsedMs = () => now() - start;
@@ -393,6 +415,7 @@ function createHpsPayments(client, target, options = {}) {
                 status = await withinBudget(elapsedMs, () => client.status({ ...target, transactionId: id }));
                 transportFailures = 0;
                 answeredQueries += 1;
+                letzteAntwort = status;
             }
             catch (e) {
                 transportFailures += 1;
@@ -416,7 +439,7 @@ function createHpsPayments(client, target, options = {}) {
             wait = nextWait(wait);
         }
         steps.push('Ausgang bleibt offen');
-        return open(id, steps);
+        return open(id, steps, letzteAntwort);
     }
     async function pay(paymentOptions) {
         const id = paymentOptions.transactionId ?? (0, transaction_id_js_1.newHpsTransactionId)();
@@ -455,7 +478,7 @@ function createHpsPayments(client, target, options = {}) {
                 return settled;
             steps.push(offeneAntwort(res));
         }
-        return resolve(id, steps, res?.responseCode !== undefined);
+        return resolve(id, steps, res?.responseCode !== undefined, res);
     }
     /**
      * Gutschrift mit geklaertem Ausgang -- EXAKT derselbe Klaerweg wie [pay]
@@ -499,7 +522,7 @@ function createHpsPayments(client, target, options = {}) {
         // Dieselbe Klaerfunktion wie [pay]: die Kennung ist die des NEUEN
         // Vorgangs, eine Statusabfrage darauf liefert also genau dessen Ausgang,
         // und der Abbruch ist derselbe Diskriminator wie bei einer Zahlung.
-        return resolve(id, steps, res?.responseCode !== undefined);
+        return resolve(id, steps, res?.responseCode !== undefined, res);
     }
     /**
      * Aufhebung (Storno/Void) einer bestehenden Zahlung mit geklaertem Ausgang.
@@ -544,7 +567,7 @@ function createHpsPayments(client, target, options = {}) {
             if (!(0, transaction_response_js_1.isCanceled)(res))
                 steps.push(offeneAntwort(res));
         }
-        return resolveCancel(id, steps);
+        return resolveCancel(id, steps, res);
     }
     return { pay, refund, cancel };
 }

package/dist/cjs/payments/hobex-hps/transaction-response.d.ts

@@ -72,6 +72,18 @@ export declare const INVALID_AMOUNT_CODE = "9003";
 export declare const AMOUNT_OUT_OF_RANGE_CODE = "100019";
 /** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
 export declare const INVALID_TID_CODE = "100108";
+/**
+ * Siehe [HPS_MEASURED_CODES]: Host-Ablehnung, falsche PIN -- nichts belastet.
+ *
+ * Zweistellig, weil ein Antwortcode des HOSTS (ISO 8583, 55 = "Incorrect
+ * PIN"), kein `9xxx`-Terminalcode und kein `100xxx`-Code der HPS-Anwendung.
+ * Daraus folgt KEINE Regel fuer andere zweistellige Codes: in derselben
+ * Familie stehen Genehmigungen (`08`, `10`, `11`, `85`). Jeder andere
+ * Host-Code bleibt eine Wissensluecke, bis er gemessen ist -- und die
+ * Zwei-9027-Regel in `payments.ts` faengt ihn nicht, weil die Statusabfrage
+ * dann nicht 9027 antwortet, sondern mit dem Code selbst.
+ */
+export declare const WRONG_PIN_CODE = "55";
 /**
  * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
  * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:

package/dist/cjs/payments/hobex-hps/transaction-response.js

@@ -28,7 +28,7 @@
  * sein kann, als `declined` gemeldet.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TERMINAL_BUSY_HTTP_STATUS = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.CARD_NOT_PRESENT_CODE = exports.ABORTED_CODE = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.TRANSACTION_CANCELED_CODE = exports.INVALID_TRANSACTION_CODE = exports.APPROVED_CODE = exports.HPS_MEASURED_CODES = void 0;
+exports.TERMINAL_BUSY_HTTP_STATUS = exports.WRONG_PIN_CODE = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.CARD_NOT_PRESENT_CODE = exports.ABORTED_CODE = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.TRANSACTION_CANCELED_CODE = exports.INVALID_TRANSACTION_CODE = exports.APPROVED_CODE = exports.HPS_MEASURED_CODES = void 0;
 exports.parseHpsTransactionResponse = parseHpsTransactionResponse;
 exports.isApproved = isApproved;
 exports.isInProgress = isInProgress;
@@ -96,6 +96,15 @@ exports.HPS_MEASURED_CODES = [
             + 'nicht; der Vorgang wird abgewiesen, bevor etwas geschieht',
         conclusive: true,
     },
+    {
+        code: '55',
+        meaning: '"PIN falsch" -- Host-Ablehnung wegen falscher PIN, die erste '
+            + 'gemessene Host-Ablehnung ueberhaupt (02.09.2026 im Betrieb, TID '
+            + '3556988, HPS 1.11.4, Firmware 2.3.9): die Zahlung antwortete direkt '
+            + 'damit, die Statusabfrage danach elfmal in Folge ebenso -- eine '
+            + 'Host-Ablehnung bleibt am Terminal abrufbar; nichts belastet',
+        conclusive: true,
+    },
 ];
 /** `responseCode` einer genehmigten Zahlung. */
 exports.APPROVED_CODE = '0';
@@ -119,6 +128,18 @@ exports.INVALID_AMOUNT_CODE = '9003';
 exports.AMOUNT_OUT_OF_RANGE_CODE = '100019';
 /** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
 exports.INVALID_TID_CODE = '100108';
+/**
+ * Siehe [HPS_MEASURED_CODES]: Host-Ablehnung, falsche PIN -- nichts belastet.
+ *
+ * Zweistellig, weil ein Antwortcode des HOSTS (ISO 8583, 55 = "Incorrect
+ * PIN"), kein `9xxx`-Terminalcode und kein `100xxx`-Code der HPS-Anwendung.
+ * Daraus folgt KEINE Regel fuer andere zweistellige Codes: in derselben
+ * Familie stehen Genehmigungen (`08`, `10`, `11`, `85`). Jeder andere
+ * Host-Code bleibt eine Wissensluecke, bis er gemessen ist -- und die
+ * Zwei-9027-Regel in `payments.ts` faengt ihn nicht, weil die Statusabfrage
+ * dann nicht 9027 antwortet, sondern mit dem Code selbst.
+ */
+exports.WRONG_PIN_CODE = '55';
 /**
  * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
  * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:

package/dist/esm/payments/hobex-hps/index.d.ts

@@ -23,5 +23,5 @@ export { type HpsPaymentEvent, type HpsPaymentEventKind, type HpsPaymentObserver
 export { type CardPaymentOutcome, type HpsPaymentResult, mayRetrySafely, } from './outcome.js';
 export { type HpsCancelOptions, type HpsPaymentOptions, type HpsPayments, type HpsPaymentsOptions, type HpsRefundOptions, createHpsPayments, } from './payments.js';
 export { MAX_TRANSACTION_ID_LENGTH, createHpsTransactionIdGenerator, isValidHpsTransactionId, newHpsTransactionId, type HpsTransactionIdGeneratorOptions, } from './transaction-id.js';
-export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, type HpsMeasuredCode, type HpsTransactionResponse, } from './transaction-response.js';
+export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, WRONG_PIN_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, type HpsMeasuredCode, type HpsTransactionResponse, } from './transaction-response.js';
 export { hobexReceiptFromHps } from './receipt.js';

package/dist/esm/payments/hobex-hps/index.js

@@ -22,5 +22,5 @@ export { HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, H
 export { mayRetrySafely, } from './outcome.js';
 export { createHpsPayments, } from './payments.js';
 export { MAX_TRANSACTION_ID_LENGTH, createHpsTransactionIdGenerator, isValidHpsTransactionId, newHpsTransactionId, } from './transaction-id.js';
-export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, } from './transaction-response.js';
+export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, WRONG_PIN_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, } from './transaction-response.js';
 export { hobexReceiptFromHps } from './receipt.js';

package/dist/esm/payments/hobex-hps/outcome.d.ts

@@ -18,8 +18,23 @@ export type CardPaymentOutcome = 'approved' | 'declined' | 'unresolved';
 export interface HpsPaymentResult {
     readonly outcome: CardPaymentOutcome;
     readonly transactionId: string;
-    /** Die letzte Antwort des Terminals, sofern eine schluessige ankam. */
+    /**
+     * Die Antwort des Terminals, die den Ausgang FESTGESCHRIEBEN hat -- nur
+     * bei `approved` und `declined`. Bei `unresolved` fehlt sie: eine
+     * Nicht-Aussage darf nicht als Beleg mitgegeben werden. Was das Terminal
+     * zuletzt gesagt hat, steht dann in [lastResponse].
+     */
     readonly response?: HpsTransactionResponse;
+    /**
+     * Die letzte Antwort des Terminals bei `unresolved`, sofern ueberhaupt
+     * eine ankam -- auch wenn sie nichts entschied (9027, 9900, ein
+     * unbekannter Code). NIE ein Beleg, sondern Material fuer Anzeige und
+     * Katalog: am 02.09.2026 sah der Bediener bei einer Antwort `55`
+     * "PIN falsch" nur "Ausgang unklar", musste raten und buchte eine
+     * abgelehnte Zahlung als bezahlt. Der Klartext des Terminals haette die
+     * Entscheidung getragen. Bei schluessigem Ausgang nicht gesetzt.
+     */
+    readonly lastResponse?: HpsTransactionResponse;
     /**
      * Verlauf der Klaerung, in Reihenfolge — der Nachweis, der im
      * Belastungsstreit gelesen wird. Behauptet nie eine Ursache, die nicht

package/dist/esm/payments/hobex-hps/payments.js

@@ -67,7 +67,7 @@ export function createHpsPayments(client, target, options = {}) {
             return `Antwort mit technischem Fehler (${TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang, Ausgang wird geklaert`;
         }
         if (isUnknownCode(res)) {
-            return `Terminal nennt einen unbekannten Code (${res.responseCode}) -- Ausgang wird geklaert`;
+            return `Terminal nennt einen unbekannten Code (${res.responseCode})${klartext(res)} -- Ausgang wird geklaert`;
         }
         return `Antwort ohne Aussage (${res.responseCode}) -- Ausgang wird geklaert`;
     }
@@ -80,10 +80,21 @@ export function createHpsPayments(client, target, options = {}) {
             return `Status: technischer Fehler (${TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang`;
         }
         if (isUnknownCode(status)) {
-            return `Status: unbekannter Code (${status.responseCode}) -- keine Aussage`;
+            return `Status: unbekannter Code (${status.responseCode})${klartext(status)} -- keine Aussage`;
         }
         return null;
     }
+    /**
+     * Der Klartext des Terminals zu einem UNBEKANNTEN Code, als Zusatz fuer den
+     * Nachweis -- oder leer, wenn keiner mitkam. Nur hier, nicht bei den
+     * gemessenen Codes: deren Bedeutung ist benannt. Bei einem unbekannten Code
+     * ist er dagegen das Einzige, was ein Mensch lesen kann -- "PIN falsch"
+     * neben `55` haette am 02.09.2026 gereicht, um nicht "bezahlt" zu buchen.
+     */
+    function klartext(res) {
+        const text = res.responseText?.trim();
+        return text ? ` "${text}"` : '';
+    }
     /** Ordnet eine Terminal-Antwort ein. `null`, wenn sie nichts entscheidet. */
     function fromResponse(res, id, steps) {
         if (!isConclusive(res))
@@ -185,9 +196,19 @@ export function createHpsPayments(client, target, options = {}) {
         }
         return null;
     }
-    function open(id, steps) {
+    /**
+     * [letzteAntwort] ist die letzte Antwort, die das Terminal in dieser
+     * Klaerung gab -- als `lastResponse` fuer Anzeige und Katalog,
+     * ausdruecklich NICHT als `response`.
+     */
+    function open(id, steps, letzteAntwort) {
         emit('resolved', steps[steps.length - 1], id);
-        return { outcome: 'unresolved', transactionId: id, steps: [...steps] };
+        return {
+            outcome: 'unresolved',
+            transactionId: id,
+            ...(letzteAntwort ? { lastResponse: letzteAntwort } : {}),
+            steps: [...steps],
+        };
     }
     /**
      * Fuehrt [call] aus, aber hoechstens so lange, wie vom [resolveBudgetMs]
@@ -260,7 +281,7 @@ export function createHpsPayments(client, target, options = {}) {
      * [NO_STATEMENT_CODE] (`9027`) beim Pollen einen Aussagewert, den es sonst
      * nicht hat. Siehe [ausGeschlossenerAntwort].
      */
-    async function resolve(id, steps, antwortMitCode = false) {
+    async function resolve(id, steps, antwortMitCode = false, letzteAntwort) {
         emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
         const start = now();
         const elapsedMs = () => now() - start;
@@ -281,6 +302,7 @@ export function createHpsPayments(client, target, options = {}) {
             try {
                 status = await withinBudget(elapsedMs, () => client.status({ ...target, transactionId: id }));
                 transportFailures = 0;
+                letzteAntwort = status;
             }
             catch (e) {
                 transportFailures += 1;
@@ -309,7 +331,7 @@ export function createHpsPayments(client, target, options = {}) {
             wait = nextWait(wait);
         }
         steps.push('Ausgang bleibt offen');
-        return open(id, steps);
+        return open(id, steps, letzteAntwort);
     }
     /**
      * Liest `9027` beim Pollen als "nicht genehmigt" -- aber NUR, wenn das
@@ -369,7 +391,7 @@ export function createHpsPayments(client, target, options = {}) {
      * Budget, Backoff und Transportfehler-Deckelung sind unveraendert aus
      * [resolve] uebernommen.
      */
-    async function resolveCancel(id, steps) {
+    async function resolveCancel(id, steps, letzteAntwort) {
         emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
         const start = now();
         const elapsedMs = () => now() - start;
@@ -390,6 +412,7 @@ export function createHpsPayments(client, target, options = {}) {
                 status = await withinBudget(elapsedMs, () => client.status({ ...target, transactionId: id }));
                 transportFailures = 0;
                 answeredQueries += 1;
+                letzteAntwort = status;
             }
             catch (e) {
                 transportFailures += 1;
@@ -413,7 +436,7 @@ export function createHpsPayments(client, target, options = {}) {
             wait = nextWait(wait);
         }
         steps.push('Ausgang bleibt offen');
-        return open(id, steps);
+        return open(id, steps, letzteAntwort);
     }
     async function pay(paymentOptions) {
         const id = paymentOptions.transactionId ?? newHpsTransactionId();
@@ -452,7 +475,7 @@ export function createHpsPayments(client, target, options = {}) {
                 return settled;
             steps.push(offeneAntwort(res));
         }
-        return resolve(id, steps, res?.responseCode !== undefined);
+        return resolve(id, steps, res?.responseCode !== undefined, res);
     }
     /**
      * Gutschrift mit geklaertem Ausgang -- EXAKT derselbe Klaerweg wie [pay]
@@ -496,7 +519,7 @@ export function createHpsPayments(client, target, options = {}) {
         // Dieselbe Klaerfunktion wie [pay]: die Kennung ist die des NEUEN
         // Vorgangs, eine Statusabfrage darauf liefert also genau dessen Ausgang,
         // und der Abbruch ist derselbe Diskriminator wie bei einer Zahlung.
-        return resolve(id, steps, res?.responseCode !== undefined);
+        return resolve(id, steps, res?.responseCode !== undefined, res);
     }
     /**
      * Aufhebung (Storno/Void) einer bestehenden Zahlung mit geklaertem Ausgang.
@@ -541,7 +564,7 @@ export function createHpsPayments(client, target, options = {}) {
             if (!isCanceled(res))
                 steps.push(offeneAntwort(res));
         }
-        return resolveCancel(id, steps);
+        return resolveCancel(id, steps, res);
     }
     return { pay, refund, cancel };
 }

package/dist/esm/payments/hobex-hps/transaction-response.d.ts

@@ -72,6 +72,18 @@ export declare const INVALID_AMOUNT_CODE = "9003";
 export declare const AMOUNT_OUT_OF_RANGE_CODE = "100019";
 /** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
 export declare const INVALID_TID_CODE = "100108";
+/**
+ * Siehe [HPS_MEASURED_CODES]: Host-Ablehnung, falsche PIN -- nichts belastet.
+ *
+ * Zweistellig, weil ein Antwortcode des HOSTS (ISO 8583, 55 = "Incorrect
+ * PIN"), kein `9xxx`-Terminalcode und kein `100xxx`-Code der HPS-Anwendung.
+ * Daraus folgt KEINE Regel fuer andere zweistellige Codes: in derselben
+ * Familie stehen Genehmigungen (`08`, `10`, `11`, `85`). Jeder andere
+ * Host-Code bleibt eine Wissensluecke, bis er gemessen ist -- und die
+ * Zwei-9027-Regel in `payments.ts` faengt ihn nicht, weil die Statusabfrage
+ * dann nicht 9027 antwortet, sondern mit dem Code selbst.
+ */
+export declare const WRONG_PIN_CODE = "55";
 /**
  * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
  * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:

package/dist/esm/payments/hobex-hps/transaction-response.js

@@ -84,6 +84,15 @@ export const HPS_MEASURED_CODES = [
             + 'nicht; der Vorgang wird abgewiesen, bevor etwas geschieht',
         conclusive: true,
     },
+    {
+        code: '55',
+        meaning: '"PIN falsch" -- Host-Ablehnung wegen falscher PIN, die erste '
+            + 'gemessene Host-Ablehnung ueberhaupt (02.09.2026 im Betrieb, TID '
+            + '3556988, HPS 1.11.4, Firmware 2.3.9): die Zahlung antwortete direkt '
+            + 'damit, die Statusabfrage danach elfmal in Folge ebenso -- eine '
+            + 'Host-Ablehnung bleibt am Terminal abrufbar; nichts belastet',
+        conclusive: true,
+    },
 ];
 /** `responseCode` einer genehmigten Zahlung. */
 export const APPROVED_CODE = '0';
@@ -107,6 +116,18 @@ export const INVALID_AMOUNT_CODE = '9003';
 export const AMOUNT_OUT_OF_RANGE_CODE = '100019';
 /** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
 export const INVALID_TID_CODE = '100108';
+/**
+ * Siehe [HPS_MEASURED_CODES]: Host-Ablehnung, falsche PIN -- nichts belastet.
+ *
+ * Zweistellig, weil ein Antwortcode des HOSTS (ISO 8583, 55 = "Incorrect
+ * PIN"), kein `9xxx`-Terminalcode und kein `100xxx`-Code der HPS-Anwendung.
+ * Daraus folgt KEINE Regel fuer andere zweistellige Codes: in derselben
+ * Familie stehen Genehmigungen (`08`, `10`, `11`, `85`). Jeder andere
+ * Host-Code bleibt eine Wissensluecke, bis er gemessen ist -- und die
+ * Zwei-9027-Regel in `payments.ts` faengt ihn nicht, weil die Statusabfrage
+ * dann nicht 9027 antwortet, sondern mit dem Code selbst.
+ */
+export const WRONG_PIN_CODE = '55';
 /**
  * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
  * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:

package/fixtures/hobex-hps-codes.json

@@ -1,11 +1,22 @@
 {
-  "version": "0.7.1",
+  "version": "0.7.2",
   "gemessenAn": {
     "tid": "3600335",
     "hpsVersion": "1.10.0",
     "firmware": "7.3.6",
     "zeitraum": "26.-28.08.2026"
   },
+  "ergaenztAn": [
+    {
+      "tid": "3556988",
+      "hpsVersion": "1.11.4",
+      "firmware": "2.3.9",
+      "zeitraum": "02.09.2026",
+      "codes": [
+        "55"
+      ]
+    }
+  ],
   "codes": [
     {
       "code": "0",
@@ -61,6 +72,11 @@
       "code": "100108",
       "meaning": "\"Invalid TID\" -- die Terminal-Kennung gibt es an diesem Geraet nicht; der Vorgang wird abgewiesen, bevor etwas geschieht",
       "conclusive": true
+    },
+    {
+      "code": "55",
+      "meaning": "\"PIN falsch\" -- Host-Ablehnung wegen falscher PIN, die erste gemessene Host-Ablehnung ueberhaupt (02.09.2026 im Betrieb, TID 3556988, HPS 1.11.4, Firmware 2.3.9): die Zahlung antwortete direkt damit, die Statusabfrage danach elfmal in Folge ebenso -- eine Host-Ablehnung bleibt am Terminal abrufbar; nichts belastet",
+      "conclusive": true
     }
   ],
   "terminalBusyHttpStatus": 409

package/fixtures/oberflaeche.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.1",
+  "version": "0.7.2",
   "aufrufe": [
     "activateCashregister",
     "cancelReceipt",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kreiseck/kasseneck-api",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "JavaScript-Zwilling von kasseneck_api (Flutter) fuer das Kasseneck-Backend",
   "license": "Apache-2.0",
   "author": "Kreiseck",