@kreiseck/kasseneck-api 0.6.45 → 0.6.49

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

@@ -0,0 +1,547 @@
+import { HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsPreflightError, } from './errors.js';
+import { newHpsTransactionId } from './transaction-id.js';
+import { isApproved, isCanceled, isConclusive, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, NOT_ABORTABLE_CODE, TECHNICAL_ERROR_CODE, TRANSACTION_CANCELED_CODE, } from './transaction-response.js';
+/** Teiler, mit dem das Abbruchbudget aus [HpsPaymentsOptions.resolveBudgetMs] entsteht. */
+const ABORT_BUDGET_DIVISOR = 6;
+export function createHpsPayments(client, target, options = {}) {
+    const resolveBudgetMs = options.resolveBudgetMs ?? 90_000;
+    const maxBackoffMs = options.maxBackoffMs ?? 10_000;
+    const maxTransportFailures = options.maxTransportFailures ?? 3;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = options.now ?? Date.now;
+    const observer = options.observer;
+    const abortBudgetMs = Math.trunc(resolveBudgetMs / ABORT_BUDGET_DIVISOR);
+    function emit(kind, message, transactionId) {
+        if (!observer)
+            return;
+        try {
+            observer({ kind, message, transactionId });
+        }
+        catch {
+            // bewusst still -- das Protokoll darf den Zahlweg nie mitreissen
+        }
+    }
+    /**
+     * Meldet eine Ausnahme, die KEIN erwarteter Connect-Fehler ist -- also
+     * einen Fehler im eigenen Auswerten statt einen an Connect oder am
+     * Terminal (z. B. eine unlesbare Antwortform).
+     */
+    function noteUnexpected(error, transactionId) {
+        if (error instanceof HpsConnectException)
+            return;
+        if (!observer)
+            return;
+        try {
+            observer({
+                kind: 'unexpectedError',
+                message: 'Unerwarteter Fehler beim Auswerten der Terminal-Antwort',
+                transactionId,
+                error,
+            });
+        }
+        catch {
+            // bewusst still
+        }
+    }
+    function describe(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    /**
+     * `null`, wenn [error] nicht der gemessene "Terminal beschaeftigt"-Fall ist.
+     * Gilt AUSDRUECKLICH nur fuer die ERZEUGENDE Anfrage (siehe `errors.ts`),
+     * niemals beim Abbruch oder beim Pollen der Statusabfrage.
+     */
+    function fromTerminalBusy(error, id, steps) {
+        if (!(error instanceof HpsConnectTerminalError) || !error.isTerminalBusy)
+            return null;
+        steps.push('Terminal beschaeftigt (HTTP 409) -- die Anfrage wurde nicht angenommen, es ist nichts geschehen');
+        emit('resolved', steps[steps.length - 1], id);
+        return { outcome: 'declined', transactionId: id, steps: [...steps] };
+    }
+    /** Verlaufseintrag fuer eine direkte Antwort, die den Ausgang NICHT festschreibt. */
+    function offeneAntwort(res) {
+        if (res.responseCode === undefined) {
+            return 'Antwort ohne Ergebniscode -- Ausgang wird geklaert';
+        }
+        if (isTechnicalError(res)) {
+            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 `Antwort ohne Aussage (${res.responseCode}) -- Ausgang wird geklaert`;
+    }
+    /** Dasselbe fuer eine Statusabfrage waehrend der Klaerung, oder `null`. */
+    function statusOhneErgebnis(status) {
+        if (isNoStatement(status)) {
+            return `Status: keine Auskunft (${status.responseCode})`;
+        }
+        if (isTechnicalError(status)) {
+            return `Status: technischer Fehler (${TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang`;
+        }
+        if (isUnknownCode(status)) {
+            return `Status: unbekannter Code (${status.responseCode}) -- keine Aussage`;
+        }
+        return null;
+    }
+    /** Ordnet eine Terminal-Antwort ein. `null`, wenn sie nichts entscheidet. */
+    function fromResponse(res, id, steps) {
+        if (!isConclusive(res))
+            return null;
+        const approved = res.responseCode === '0';
+        steps.push(approved ? 'Terminal: genehmigt' : `Terminal: abgelehnt (${res.responseCode})`);
+        emit('resolved', steps[steps.length - 1], id);
+        return { outcome: approved ? 'approved' : 'declined', transactionId: id, response: res, steps: [...steps] };
+    }
+    /**
+     * Ordnet die DIREKTE Antwort auf einen Aufhebungs-Request ein. Fast dasselbe
+     * wie [fromResponse] -- diese Antwort betrifft die Aufhebung selbst und
+     * traegt deren eigenen `responseCode`. Mit genau einer Ausnahme:
+     * [TRANSACTION_CANCELED_CODE] (`9011`).
+     *
+     * Ueber [fromResponse] wuerde `9011` zu `declined` -- also "die Aufhebung
+     * hat nicht gegriffen, es ist weiterhin belastet". Das waere die teure
+     * Richtung: es meldet "belastet" fuer einen Vorgang, der aufgehoben ist, und
+     * laedt zu einer Rueckerstattung ein, die der Kunde ein zweites Mal bekaeme.
+     * Es widerspraeche ausserdem [fromCancelStatus], die aus demselben Code das
+     * Gegenteil ableitet.
+     *
+     * Was `9011` auf dem DIREKTEN Weg genau heisst, ist UNGEMESSEN -- am
+     * naechstliegenden "der Vorgang ist (bereits) aufgehoben", aber das ist eine
+     * Lesart, keine Messung. Deshalb weder Erfolg noch Ablehnung hier, sondern
+     * NICHT SCHLUESSIG: die Klaerung fragt den Zustand der Originalzahlung ab
+     * und entscheidet ihn dort mit dem gemessenen Diskriminator, statt zu raten.
+     */
+    function fromCancelResponse(res, id, steps) {
+        if (isCanceled(res)) {
+            steps.push(`Aufhebung mit ${TRANSACTION_CANCELED_CODE} beantwortet -- mehrdeutig, der Zustand der Originalzahlung wird abgefragt`);
+            return null;
+        }
+        return fromResponse(res, id, steps);
+    }
+    /**
+     * Ordnet die Statusabfrage einer OFFENEN AUFHEBUNG ein. `null`, wenn sie
+     * nichts entscheidet.
+     *
+     * Die Abfrage laeuft auf die Kennung der ORIGINALZAHLUNG. Ihr
+     * `responseCode` beschreibt deshalb den Zustand DIESER Zahlung, nicht den
+     * Ausgang der Aufhebung -- er wird hier UEBERSETZT, nicht wie bei
+     * [fromResponse] gelesen. Am 26./28.08.2026 gemessen, nachdem eine
+     * genehmigte Zahlung per Void aufgehoben wurde:
+     *
+     * - `9011` "Transaction Canceled" -> die Aufhebung hat gewirkt -> `approved`.
+     * - `'0'` -> die Originalzahlung steht unveraendert -> die Aufhebung hat
+     *   NICHT gewirkt -> `declined`. Keine schlechte Nachricht ueber die
+     *   Zahlung, sondern ueber die Aufhebung: es ist weiterhin belastet, und
+     *   die Aufhebung muss wiederholt werden. ABER erst ab der ZWEITEN
+     *   beantworteten Abfrage, siehe [firstQuery].
+     * - `9027` und jeder andere oder fehlende Code -> keine Auskunft, weiter
+     *   klaeren; am Ende `unresolved`, niemals ein geratenes Ergebnis.
+     *
+     * ## Warum `'0'` eine Karenz braucht
+     *
+     * Die Klaerung startet unmittelbar, nachdem der Void-Request abgerissen
+     * ist, und ihre erste Abfrage laeuft ohne Pause. Anders als bei [pay] liegt
+     * kein Abbruch-Roundtrip dazwischen, der Zeit verstreichen liesse. Genau in
+     * diesem Fenster kann der Void beim Terminal noch unterwegs sein und die
+     * Abfrage trotzdem schon `'0'` melden.
+     *
+     * Ein voreiliges "hat nicht gegriffen" ist NICHT harmlos: nach dem
+     * Tagesabschluss ist die Folgehandlung eine RUECKERSTATTUNG -- und dann
+     * bekommt der Kunde sein Geld zweimal. Deshalb entscheidet `'0'` erst ab der
+     * zweiten beantworteten Abfrage. Ein tatsaechlich nicht gelandeter Void
+     * antwortet eine Sekunde spaeter wieder `'0'`; der Preis ist diese eine
+     * Sekunde. Reicht das Budget nur fuer eine einzige Abfrage, endet die
+     * Klaerung bei `unresolved` -- wir sagen dann, dass wir es nicht wissen,
+     * statt es zu raten.
+     *
+     * [state] `=== 'VOID'` gilt zusaetzlich als Beleg, aber niemals als
+     * notwendige Bedingung -- auf der gemessenen Firmware ist `state` in jeder
+     * bisher gesehenen Antwort `undefined`. Bleibt nur mitgelesen, weil ein
+     * ausdrueckliches `'VOID'` -- wo eine Firmware es denn liefert -- eine
+     * unmissverstaendliche positive Aussage ist, die kein falsches `approved`
+     * erzeugen kann.
+     *
+     * [firstQuery] ist `true`, wenn dies die erste BEANTWORTETE Statusabfrage
+     * dieser Klaerung ist. Gescheiterte Abfragen zaehlen nicht mit: sie lassen
+     * zwar Zeit verstreichen, liefern aber keine Auskunft, an der sich ein
+     * `'0'` bestaetigen liesse.
+     */
+    function fromCancelStatus(status, id, steps, firstQuery) {
+        const voided = isCanceled(status) || status.state?.trim().toUpperCase() === 'VOID';
+        if (voided) {
+            steps.push(`Terminal: Aufhebung bestaetigt (${status.responseCode ?? status.state})`);
+            emit('resolved', steps[steps.length - 1], id);
+            return { outcome: 'approved', transactionId: id, response: status, steps: [...steps] };
+        }
+        if (isApproved(status)) {
+            if (firstQuery) {
+                steps.push('Terminal: Originalzahlung noch unveraendert (0) -- die Aufhebung koennte noch unterwegs sein, wird erneut abgefragt');
+                return null;
+            }
+            steps.push('Terminal: Originalzahlung steht unveraendert (0) -- die Aufhebung hat nicht gegriffen');
+            emit('resolved', steps[steps.length - 1], id);
+            return { outcome: 'declined', transactionId: id, response: status, steps: [...steps] };
+        }
+        return null;
+    }
+    function open(id, steps) {
+        emit('resolved', steps[steps.length - 1], id);
+        return { outcome: 'unresolved', transactionId: id, steps: [...steps] };
+    }
+    /**
+     * Fuehrt [call] aus, aber hoechstens so lange, wie vom [resolveBudgetMs]
+     * uebrig ist -- sonst waere die Klaerung nicht durch das Budget begrenzt,
+     * sondern durch das (deutlich groessere) Zeitlimit des Connect-Clients je
+     * einzelnem Aufruf. [cap] deckelt zusaetzlich einen einzelnen Schritt
+     * (siehe [abortBudgetMs]).
+     */
+    function withinBudget(elapsedMs, call, cap) {
+        let left = resolveBudgetMs - elapsedMs();
+        if (cap !== undefined && cap < left)
+            left = cap;
+        if (left <= 0) {
+            return Promise.reject(new HpsClarifyTimeoutError(resolveBudgetMs));
+        }
+        return withTimeout(call(), left);
+    }
+    function withTimeout(promise, ms) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new HpsClarifyTimeoutError(ms)), ms);
+            promise.then((v) => {
+                clearTimeout(timer);
+                resolve(v);
+            }, (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+        });
+    }
+    function nextWait(current) {
+        if (current === 0)
+            return 1000;
+        const doubled = current * 2;
+        return doubled > maxBackoffMs ? maxBackoffMs : doubled;
+    }
+    /**
+     * Versucht den Abbruch GENAU EINMAL. Liefert ein Ergebnis nur im einen
+     * beweisbaren Fall: Connect quittiert den Abbruch mit `responseCode === '0'`.
+     * In jedem anderen Fall `null` -- der Aufrufer pollt dann weiter.
+     */
+    async function tryAbort(id, steps, elapsedMs) {
+        let res;
+        try {
+            res = await withinBudget(elapsedMs, () => client.abort({ ...target, transactionId: id }), abortBudgetMs);
+        }
+        catch (e) {
+            steps.push(`Abbruch nicht bestaetigt (${describe(e)}) -- ob er wirkte, ist offen, Ausgang wird abgefragt`);
+            noteUnexpected(e, id);
+            return null;
+        }
+        if (res.responseCode === undefined) {
+            steps.push('Abbruch ohne Ergebniscode quittiert -- das beweist nichts, Ausgang wird abgefragt');
+            return null;
+        }
+        if (res.responseCode !== '0') {
+            steps.push(isNotAbortable(res)
+                ? `Abbruch abgelehnt (${NOT_ABORTABLE_CODE}) -- der Vorgang ist nicht mehr abbrechbar, Ausgang wird abgefragt`
+                : `Abbruch abgelehnt (${res.responseCode}) -- Grund unbekannt, Ausgang wird abgefragt`);
+            return null;
+        }
+        steps.push('Abbruch bestaetigt -- der Vorgang war noch abbrechbar, es ist nichts belastet');
+        emit('resolved', steps[steps.length - 1], id);
+        return { outcome: 'declined', transactionId: id, response: res, steps: [...steps] };
+    }
+    /** Klaert einen offenen Ausgang: erst abbrechen, dann abfragen -- bis das Terminal etwas sagt oder das Budget aufgebraucht ist. */
+    /**
+     * `antwortMitCode` heisst: das Terminal hat auf die ERZEUGENDE Anfrage eine
+     * Antwort MIT Ergebniscode geliefert, deren Bedeutung wir nur nicht kennen.
+     * Dann ist der Vorgang am Geraet abgeschlossen -- und erst dadurch bekommt
+     * [NO_STATEMENT_CODE] (`9027`) beim Pollen einen Aussagewert, den es sonst
+     * nicht hat. Siehe [ausGeschlossenerAntwort].
+     */
+    async function resolve(id, steps, antwortMitCode = false) {
+        emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
+        const start = now();
+        const elapsedMs = () => now() - start;
+        const aborted = await tryAbort(id, steps, elapsedMs);
+        if (aborted)
+            return aborted;
+        let wait = 0;
+        let transportFailures = 0;
+        let ohneAuskunft = 0;
+        while (elapsedMs() < resolveBudgetMs) {
+            if (wait > 0) {
+                const left = resolveBudgetMs - elapsedMs();
+                await sleep(Math.min(wait, left));
+                if (elapsedMs() >= resolveBudgetMs)
+                    break;
+            }
+            let status;
+            try {
+                status = await withinBudget(elapsedMs, () => client.status({ ...target, transactionId: id }));
+                transportFailures = 0;
+            }
+            catch (e) {
+                transportFailures += 1;
+                steps.push(`Statusabfrage gescheitert (${transportFailures}): ${describe(e)}`);
+                noteUnexpected(e, id);
+                if (transportFailures >= maxTransportFailures) {
+                    steps.push('Terminal antwortet nicht -- Ausgang bleibt offen');
+                    break;
+                }
+                wait = nextWait(wait);
+                continue;
+            }
+            const settled = fromResponse(status, id, steps);
+            if (settled)
+                return settled;
+            if (isNoStatement(status)) {
+                ohneAuskunft += 1;
+                const geklaert = ausGeschlossenerAntwort(id, steps, status, antwortMitCode, ohneAuskunft);
+                if (geklaert)
+                    return geklaert;
+            }
+            else {
+                ohneAuskunft = 0;
+            }
+            steps.push(statusOhneErgebnis(status) ?? 'Status: noch kein Ergebniscode');
+            wait = nextWait(wait);
+        }
+        steps.push('Ausgang bleibt offen');
+        return open(id, steps);
+    }
+    /**
+     * Liest `9027` beim Pollen als "nicht genehmigt" -- aber NUR, wenn das
+     * Terminal die erzeugende Anfrage bereits mit einem Ergebniscode beantwortet
+     * hat, und erst ab der ZWEITEN Abfrage in Folge.
+     *
+     * **Warum das ueberhaupt geht.** [NO_STATEMENT_CODE] ist sonst eine reine
+     * Nicht-Aussage: dieselbe `9027` steht fuer einen laufenden, einen
+     * abgebrochenen und einen nie gesehenen Vorgang. Hat das Terminal aber eine
+     * Antwort MIT Code geliefert, faellt "laeuft noch" weg -- der Vorgang ist
+     * dort beendet -- und "nie gesehen" ebenso, denn zu genau dieser Kennung
+     * wurde uns gerade geantwortet. Uebrig bleibt "beendet und nicht genehmigt".
+     *
+     * **Gegenprobe** (28.08.2026, TID 3600335, jeweils nach abgeschlossenem
+     * Vorgang): genehmigt (Beleg 408811) -> Statusabfrage `0`, dreimal
+     * wiederholt; abgelehnt mit `100003` -> `9027`, zweimal; abgelehnt mit
+     * `9003` -> `9027`. Eine genehmigte Zahlung antwortet also nicht `9027`.
+     *
+     * **Warum erst ab der zweiten Abfrage.** Die erste laeuft unmittelbar nach
+     * der Antwort -- das Fenster, in dem der Datensatz am Terminal noch nicht
+     * stehen koennte. Waere er es nicht und wir lesen `9027` als "abgelehnt",
+     * entstuende die Doppelbelastung vom 24.08.2026 an einer neuen Stelle.
+     * Dieselbe Absicherung traegt bereits [fromCancelStatus].
+     *
+     * `undefined` heisst: nicht entschieden, weiter pollen.
+     */
+    function ausGeschlossenerAntwort(id, steps, status, antwortMitCode, ohneAuskunft) {
+        if (!antwortMitCode)
+            return undefined;
+        if (ohneAuskunft < 2)
+            return undefined;
+        steps.push(`Statusabfrage zweimal ohne Auskunft (${status.responseCode}), obwohl das `
+            + 'Terminal den Vorgang bereits beantwortet hatte -- er ist beendet und '
+            + 'nicht genehmigt, es ist nichts belastet');
+        emit('resolved', steps[steps.length - 1], id);
+        return {
+            outcome: 'declined',
+            transactionId: id,
+            response: status,
+            steps: [...steps],
+        };
+    }
+    /**
+     * Klaert eine offene Aufhebung -- eigene Fassung statt [resolve], weil die
+     * Kennung hier die der URSPRUENGLICHEN Zahlung ist.
+     *
+     * Zwei Unterschiede zu [resolve]:
+     *
+     * 1. Die Antwort der Statusabfrage wird ueber [fromCancelStatus]
+     *    eingeordnet, NICHT ueber [fromResponse] -- der `responseCode` der
+     *    Originalkennung bedeutet hier etwas anderes als bei [pay]/[refund].
+     * 2. KEIN [tryAbort]-Versuch. Der Abbruch greift nur, solange ein Vorgang
+     *    noch abbrechbar ist; die Originalzahlung, deren Kennung hier vorliegt,
+     *    ist laengst abgeschlossen und antwortet gemessen mit `100010`. Ein
+     *    Abbruchversuch darauf waere sinnlos und koennte hoechstens fehlleiten.
+     *
+     * Budget, Backoff und Transportfehler-Deckelung sind unveraendert aus
+     * [resolve] uebernommen.
+     */
+    async function resolveCancel(id, steps) {
+        emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
+        const start = now();
+        const elapsedMs = () => now() - start;
+        let wait = 0;
+        let transportFailures = 0;
+        // Zaehlt nur BEANTWORTETE Statusabfragen -- Grundlage der Karenz fuer den
+        // `'0'`-Fall, siehe [fromCancelStatus].
+        let answeredQueries = 0;
+        while (elapsedMs() < resolveBudgetMs) {
+            if (wait > 0) {
+                const left = resolveBudgetMs - elapsedMs();
+                await sleep(Math.min(wait, left));
+                if (elapsedMs() >= resolveBudgetMs)
+                    break;
+            }
+            let status;
+            try {
+                status = await withinBudget(elapsedMs, () => client.status({ ...target, transactionId: id }));
+                transportFailures = 0;
+                answeredQueries += 1;
+            }
+            catch (e) {
+                transportFailures += 1;
+                steps.push(`Statusabfrage gescheitert (${transportFailures}): ${describe(e)}`);
+                noteUnexpected(e, id);
+                if (transportFailures >= maxTransportFailures) {
+                    steps.push('Terminal antwortet nicht -- Ausgang bleibt offen');
+                    break;
+                }
+                wait = nextWait(wait);
+                continue;
+            }
+            const settled = fromCancelStatus(status, id, steps, answeredQueries === 1);
+            if (settled)
+                return settled;
+            // Der `'0'`-Karenzfall hat seinen eigenen, aussagekraeftigeren Eintrag
+            // schon in [fromCancelStatus] gesetzt.
+            if (!isApproved(status)) {
+                steps.push(statusOhneErgebnis(status) ?? 'Status: Aufhebung noch nicht bestaetigt');
+            }
+            wait = nextWait(wait);
+        }
+        steps.push('Ausgang bleibt offen');
+        return open(id, steps);
+    }
+    async function pay(paymentOptions) {
+        const id = paymentOptions.transactionId ?? newHpsTransactionId();
+        const steps = [];
+        // Das try liegt bewusst ENG um den Netzweg: was danach kommt, ist unser
+        // eigenes Auswerten und soll nicht stillschweigend als "Terminal hat
+        // nicht geantwortet" durchgehen.
+        let res;
+        try {
+            res = await client.payment({
+                ...target,
+                transactionId: id,
+                amountCents: paymentOptions.amountCents,
+                tipCents: paymentOptions.tipCents,
+                reference: paymentOptions.reference,
+                currency: paymentOptions.currency,
+                language: paymentOptions.language,
+            });
+        }
+        catch (e) {
+            if (e instanceof HpsPreflightError) {
+                // Beweisbar nichts gesendet -- kein Ausgang, sondern ein Aufruffehler.
+                // Wird unveraendert weitergeworfen, damit er sichtbar bleibt statt als
+                // offener Ausgang zu enden (Zwilling: Dart's `ArgumentError`-Zweig).
+                throw e;
+            }
+            const busy = fromTerminalBusy(e, id, steps);
+            if (busy)
+                return busy;
+            steps.push(`Zahlung abgebrochen: ${describe(e)}`);
+            noteUnexpected(e, id);
+        }
+        if (res) {
+            const settled = fromResponse(res, id, steps);
+            if (settled)
+                return settled;
+            steps.push(offeneAntwort(res));
+        }
+        return resolve(id, steps, res?.responseCode !== undefined);
+    }
+    /**
+     * Gutschrift mit geklaertem Ausgang -- EXAKT derselbe Klaerweg wie [pay]
+     * (Abbruch eingeschlossen), siehe Klassendoku oben. [transactionId] ist die
+     * Kennung des NEUEN Vorgangs (der Gutschrift selbst), nicht die der
+     * Zahlung, auf die sie sich ueber [HpsRefundOptions.originalTransactionId]
+     * referenziert.
+     */
+    async function refund(refundOptions) {
+        const id = refundOptions.transactionId ?? newHpsTransactionId();
+        const steps = [];
+        // Das try liegt bewusst ENG um den Netzweg -- siehe Begruendung in [pay].
+        let res;
+        try {
+            res = await client.refund({
+                ...target,
+                transactionId: id,
+                originalTransactionId: refundOptions.originalTransactionId,
+                amountCents: refundOptions.amountCents,
+                reference: refundOptions.reference,
+                currency: refundOptions.currency,
+                language: refundOptions.language,
+            });
+        }
+        catch (e) {
+            if (e instanceof HpsPreflightError) {
+                throw e;
+            }
+            const busy = fromTerminalBusy(e, id, steps);
+            if (busy)
+                return busy;
+            steps.push(`Gutschrift abgebrochen: ${describe(e)}`);
+            noteUnexpected(e, id);
+        }
+        if (res) {
+            const settled = fromResponse(res, id, steps);
+            if (settled)
+                return settled;
+            steps.push(offeneAntwort(res));
+        }
+        // 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);
+    }
+    /**
+     * Aufhebung (Storno/Void) einer bestehenden Zahlung mit geklaertem Ausgang.
+     *
+     * [transactionId] ist die vom TERMINAL vergebene Kennung der
+     * URSPRUENGLICHEN Zahlung -- nicht die eines neuen Vorgangs. Der direkte
+     * Antwortweg wird trotzdem ueber [fromCancelResponse] eingeordnet: die
+     * Direktantwort auf einen Aufhebungs-Request traegt einen eigenen
+     * `responseCode` fuer die Aufhebung selbst. Erst wenn dieser direkte Weg
+     * abbricht und nachgefragt werden muss, aendert sich die Frage -- siehe
+     * [resolveCancel].
+     */
+    async function cancel(cancelOptions) {
+        const id = cancelOptions.transactionId;
+        const steps = [];
+        let res;
+        try {
+            res = await client.cancel({
+                ...target,
+                transactionId: id,
+                amountCents: cancelOptions.amountCents,
+                currency: cancelOptions.currency,
+                language: cancelOptions.language,
+            });
+        }
+        catch (e) {
+            if (e instanceof HpsPreflightError) {
+                throw e;
+            }
+            const busy = fromTerminalBusy(e, id, steps);
+            if (busy)
+                return busy;
+            steps.push(`Aufhebung abgebrochen: ${describe(e)}`);
+            noteUnexpected(e, id);
+        }
+        if (res) {
+            const settled = fromCancelResponse(res, id, steps);
+            if (settled)
+                return settled;
+            // Kein Sammel-Eintrag fuer 9011: [fromCancelResponse] hat dafuer
+            // bereits den zutreffenden Eintrag gesetzt.
+            if (!isCanceled(res))
+                steps.push(offeneAntwort(res));
+        }
+        return resolveCancel(id, steps);
+    }
+    return { pay, refund, cancel };
+}

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

@@ -0,0 +1,28 @@
+import type { HobexReceipt } from '../../models/hobex-receipt.js';
+import type { HpsTransactionResponse } from './transaction-response.js';
+/**
+ * Macht aus der Terminal-Antwort den Kasseneck-Beleg -- Zwilling von
+ * `HobexReceipt.fromHps` (kasseneck_api, `lib/models/hobex_receipt.dart`).
+ *
+ * Ohne diese Bruecke endet eine gelungene HPS-Zahlung im Nichts: der
+ * Buchungsweg erwartet einen Beleg (`cardPaymentData`, siehe
+ * [hobexReceiptToCardPaymentData]), und die Antwort des Terminals ist keiner.
+ *
+ * Drei Eigenheiten, alle am 28.08.2026 am Terminal 3600335 gemessen und
+ * nicht aus der Doku uebernommen:
+ *
+ * 1. **`cvm` kommt als ZAHL** (`3`), nicht als Text. Ungewandelt scheitert
+ *    [hobexReceiptNeedsSignature] (`=== '1'`) stumm an einer `1` -- und eine
+ *    verlangte Unterschrift bliebe ungefragt. Deshalb ueber [text].
+ * 2. **Nicht gefuehrte Felder kommen als `null`** (gemessen: `currency`,
+ *    `reference`, `source`, `state`). Sie werden zu LEEREM Text, nie zu
+ *    `"null"` -- sonst stuende das Wort auf dem Beleg.
+ * 3. `cvm` wird aus [HpsTransactionResponse.raw] gelesen und nicht aus einem
+ *    eigenen Feld -- genauso wie im Dart-Vorbild (`res.raw['cvm']`). Der
+ *    Rohsatz ist die Quelle, damit hier nichts eigenes danebenlaeuft.
+ *
+ * Der Betrag geht ueber [euroToCents], die eine gehaertete Stelle des Pakets:
+ * die Terminal-Antwort ist eine fremde Antwort, und ein nicht-endlicher Wert
+ * ergaebe sonst lautlos `NaN`.
+ */
+export declare function hobexReceiptFromHps(res: HpsTransactionResponse): HobexReceipt;

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

@@ -0,0 +1,57 @@
+import { CreditCardProvider } from '../../enums/index.js';
+import { euroToCents } from '../../money.js';
+/**
+ * Macht aus der Terminal-Antwort den Kasseneck-Beleg -- Zwilling von
+ * `HobexReceipt.fromHps` (kasseneck_api, `lib/models/hobex_receipt.dart`).
+ *
+ * Ohne diese Bruecke endet eine gelungene HPS-Zahlung im Nichts: der
+ * Buchungsweg erwartet einen Beleg (`cardPaymentData`, siehe
+ * [hobexReceiptToCardPaymentData]), und die Antwort des Terminals ist keiner.
+ *
+ * Drei Eigenheiten, alle am 28.08.2026 am Terminal 3600335 gemessen und
+ * nicht aus der Doku uebernommen:
+ *
+ * 1. **`cvm` kommt als ZAHL** (`3`), nicht als Text. Ungewandelt scheitert
+ *    [hobexReceiptNeedsSignature] (`=== '1'`) stumm an einer `1` -- und eine
+ *    verlangte Unterschrift bliebe ungefragt. Deshalb ueber [text].
+ * 2. **Nicht gefuehrte Felder kommen als `null`** (gemessen: `currency`,
+ *    `reference`, `source`, `state`). Sie werden zu LEEREM Text, nie zu
+ *    `"null"` -- sonst stuende das Wort auf dem Beleg.
+ * 3. `cvm` wird aus [HpsTransactionResponse.raw] gelesen und nicht aus einem
+ *    eigenen Feld -- genauso wie im Dart-Vorbild (`res.raw['cvm']`). Der
+ *    Rohsatz ist die Quelle, damit hier nichts eigenes danebenlaeuft.
+ *
+ * Der Betrag geht ueber [euroToCents], die eine gehaertete Stelle des Pakets:
+ * die Terminal-Antwort ist eine fremde Antwort, und ein nicht-endlicher Wert
+ * ergaebe sonst lautlos `NaN`.
+ */
+export function hobexReceiptFromHps(res) {
+    return {
+        transactionId: text(res.transactionId),
+        tid: text(res.tid),
+        receipt: text(res.receipt),
+        approvalCode: text(res.approvalCode),
+        reference: res.reference,
+        // Bruchteilssekunden samt Zeitzonenversatz kappen und "T" durch ein
+        // Leerzeichen ersetzen -- Wort fuer Wort wie im Dart-Vorbild.
+        transactionDate: text(res.transactionDate).split('.')[0].split('T').join(' '),
+        cardNumber: text(res.cardNumber),
+        cardExpiry: text(res.cardExpiry),
+        brand: text(res.brand),
+        cardIssuer: text(res.cardIssuer),
+        responseCode: text(res.responseCode),
+        transactionType: text(res.transactionType),
+        currency: text(res.currency),
+        amountCents: euroToCents(res.amount ?? 0),
+        tipCents: euroToCents(res.tip ?? 0),
+        cvm: text(res.raw.cvm),
+        // Der Provider ergibt sich aus dem Weg, nicht aus dem JSON: was hier
+        // ankommt, kam ueber HPS. Genau daran haengt, ob
+        // [hobexReceiptToCardPaymentData] die HPS-Zusatzfelder mitgibt.
+        creditCardProvider: CreditCardProvider.hobexHps,
+    };
+}
+/** `null`/`undefined` werden zu leerem Text, alles andere wortgetreu. */
+function text(wert) {
+    return wert === null || wert === undefined ? '' : String(wert);
+}