@kreiseck/kasseneck-api 0.18.0 → 0.20.0

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

@@ -25,12 +25,22 @@
  * bis dahin unbenannter Code ([TECHNICAL_ERROR_CODE], `9900`) war darueber
  * schluessig und haette eine Zahlung, unter der tatsaechlich Geld geflossen
  * sein kann, als `declined` gemeldet.
+ *
+ * Seit 16.09.2026 kommt die TECS-Liste dazu (`tecs-codes.ts`): das HPS
+ * reicht die Codes der TECS-Plattform durch, auf der hobex autorisiert. Neu
+ * sind dabei [HpsCode.sendReversal] (Storno nachschicken, siehe
+ * `payments.ts`) und die Schreibweise: TECS fuehrt `0055`, das Terminal
+ * sendet `55` -- [normalizeHpsCode] macht beides zu einem Code.
+ *
+ * **Einen neuen Code aufnehmen:** Eintrag hier oder in `tecs-codes.ts`,
+ * derselbe im Dart-Zwilling, `npm run fixtures:hobex-hps-codes`; ein neuer
+ * Grund braucht in jeder Kasse eine Uebersetzung.
  */
 /** Wie ein Ergebniscode den Ausgang eines Vorgangs bestimmt. */
 export type HpsCodeEffect = 
 /** Schreibt den Ausgang fest: `'0'` genehmigt, jeder andere abgelehnt. */
 'conclusive'
-/** Gemessen oder dokumentiert, aber KEINE Aussage (9027, 9900, 100011). */
+/** Gemessen oder dokumentiert, aber KEINE Aussage (9027, 100011, fremde TECS-Produkte). */
  | 'noStatement'
 /**
  * Der Host war beteiligt, das Terminal storniert nicht selbst -- ob belastet
@@ -42,9 +52,12 @@ export type HpsCodeEffect =
 export type HpsCodeSource = 
 /** Am Geraet gemessen (`doc/kartenzahlung.md` im Dart-Zwilling). */
 'measured'
-/** Aus der Antwortcodeliste von hobex (erhalten 11.09.2026). */
+/**
+ * Von hobex dokumentiert: HPS-Liste (11.09.2026) oder TECS-Liste
+ * (16.09.2026, dann ist `tecsTitle` gesetzt).
+ */
  | 'documented'
-/** Beides. */
+/** Beides: gemessen und von hobex bestaetigt. */
  | 'measuredAndDocumented';
 /**
  * Worauf eine Kasse reagiert -- der Grund hinter einem Ergebniscode. Mehrere
@@ -53,12 +66,12 @@ export type HpsCodeSource =
  * fuer den Bediener steht in [HPS_REASON_HINTS]; eine Kasse mit eigener
  * Uebersetzung schluesselt ueber den Grund selbst.
  */
-export type HpsCodeReason = 'approved' | 'aborted' | 'noCard' | 'cardReadFailed' | 'cardDeclined' | 'wrongPin' | 'amountInvalid' | 'tipNotSelected' | 'terminalBusy' | 'terminalBlocked' | 'terminalSetup' | 'terminalFault' | 'requestRejected' | 'invalidTransaction' | 'refundPassword' | 'refundDisabled' | 'hostTimeoutReversed' | 'hostFault' | 'internalError' | 'canceled' | 'notAbortable' | 'noStatement' | 'technicalError' | 'unknown';
+export type HpsCodeReason = 'approved' | 'approvedWithCondition' | 'aborted' | 'noCard' | 'cardReadFailed' | 'cardDeclined' | 'issuerDeclined' | 'cardBlocked' | 'cardExpired' | 'insufficientFunds' | 'wrongPin' | 'pinTriesExceeded' | 'pinRequired' | 'amountInvalid' | 'tipNotSelected' | 'terminalBusy' | 'terminalBlocked' | 'terminalSetup' | 'acquirerSetup' | 'terminalFault' | 'requestRejected' | 'hostRejected' | 'hostUnavailable' | 'invalidTransaction' | 'refundPassword' | 'refundDisabled' | 'refundRejected' | 'hostTimeoutReversed' | 'reversedByHost' | 'voidedAfterHostFault' | 'hostFault' | 'hostTimeout' | 'internalError' | 'canceled' | 'cancelDenied' | 'originalDeclined' | 'notAbortable' | 'noStatement' | 'technicalError' | 'unknown';
 /** Der Satz fuer den Bediener je Grund, deutsch. */
 export declare const HPS_REASON_HINTS: Readonly<Record<HpsCodeReason, string>>;
 /**
- * Die beiden Gruende hinter einem Code mit `effect: 'hostUncertain'`: ob Geld
- * geflossen ist, weiss das Terminal nicht.
+ * Die Gruende hinter einem Code mit `effect: 'hostUncertain'`: ob (und wie
+ * viel) Geld geflossen ist, weiss das Terminal nicht.
  */
 export declare function isHostUncertainReason(reason: HpsCodeReason | undefined): boolean;
 /** Ein Ergebniscode, dessen Bedeutung feststeht (gemessen oder dokumentiert). */
@@ -88,6 +101,20 @@ export interface HpsCode extends HpsMeasuredCode {
      * nichts (gemessen fuer `100108`). Siehe [isConclusiveAsStatus].
      */
     readonly rejectsRequest: boolean;
+    /**
+     * Bei diesem Code wird ein Storno nachgeschickt: der Host hat nicht oder
+     * nicht brauchbar geantwortet, und das Terminal nimmt den Vorgang nicht
+     * selbst zurueck. Nur bei `effect: 'hostUncertain'`. Vorgabe von hobex
+     * (16.09.2026) zu `9908`: "ein Timeout wie jeder andere. Richtigerweise
+     * sollte in dem Fall ein Storno nachgeschickt werden."
+     */
+    readonly sendReversal: boolean;
+    /**
+     * Titel in der TECS-Liste (16.09.2026), wenn der Code dort steht -- sonst
+     * `null`. Bei gemessenen Codes weicht er vom [title] ab (`55`: "PIN
+     * falsch" gegen "Incorrect PIN").
+     */
+    readonly tecsTitle: string | null;
 }
 /**
  * Die vollstaendige Codetabelle — Vertrag mit dem Dart-Zwilling
@@ -228,7 +255,19 @@ export declare const TERMINAL_BUSY_HTTP_STATUS = 409;
  * HTTP-Status ist kein `responseCode`.
  */
 export declare const NOT_FOUND_HTTP_STATUS = 404;
-/** Der Eintrag zu [code] in [HPS_CODES], oder `undefined`, wenn seine Bedeutung nicht feststeht. */
+/**
+ * Die Schreibweise, unter der [code] in [HPS_CODES] steht: ein rein
+ * numerischer Code ohne fuehrende Nullen (`0055` -> `55`, `0000` -> `0`),
+ * jeder andere unveraendert. Ohne diese Angleichung waere ein `0000` kein
+ * `0` -- und damit eine ABLEHNUNG einer genehmigten Zahlung.
+ * [parseHpsTransactionResponse] gleicht deshalb schon beim Einlesen an.
+ */
+export declare function normalizeHpsCode(code: string): string;
+/**
+ * Der Eintrag zu [code] in [HPS_CODES], oder `undefined`, wenn seine
+ * Bedeutung nicht feststeht. Findet beide Schreibweisen
+ * ([normalizeHpsCode]) und die Familien mit Platzhalter (`8105` -> `81xx`).
+ */
 export declare function hpsCodeInfo(code: string | undefined): HpsCode | undefined;
 /**
  * Der Grund zu [code] -- `'unknown'` fuer einen Code ausserhalb der Tabelle,
@@ -294,7 +333,10 @@ export declare function isNotAbortable(res: Pick<HpsTransactionResponse, 'respon
  * gemessen. `100011` ist dokumentiert, aber nie gesehen.
  */
 export declare function isNoStatement(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
-/** `true`, wenn das Terminal einen technischen Fehler meldet (9900). */
+/**
+ * `true`, wenn das Terminal einen technischen Fehler meldet (9900). Seit der
+ * TECS-Liste zugleich [isHostUncertain]: ob belastet wurde, ist offen.
+ */
 export declare function isTechnicalError(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
 /**
  * `true`, wenn der Vorgang unter dieser Kennung aufgehoben wurde (9011).
@@ -327,6 +369,12 @@ export declare function isConclusiveAsStatus(res: Pick<HpsTransactionResponse, '
  * Speicher des Terminals, nicht den des Hosts.
  */
 export declare function isHostUncertain(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/**
+ * `true`, wenn zu diesem Code ein Storno nachzuschicken ist
+ * ([HpsCode.sendReversal]) -- der Host hat nicht oder nicht brauchbar
+ * geantwortet, etwa `9908`.
+ */
+export declare function needsReversal(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
 /**
  * `true`, wenn ein Ergebniscode VORHANDEN ist, dessen Bedeutung aber nicht
  * feststeht -- er fehlt in [HPS_CODES]. Ein Code, den dieses Modell schlicht

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

@@ -25,66 +25,84 @@
  * bis dahin unbenannter Code ([TECHNICAL_ERROR_CODE], `9900`) war darueber
  * schluessig und haette eine Zahlung, unter der tatsaechlich Geld geflossen
  * sein kann, als `declined` gemeldet.
+ *
+ * Seit 16.09.2026 kommt die TECS-Liste dazu (`tecs-codes.ts`): das HPS
+ * reicht die Codes der TECS-Plattform durch, auf der hobex autorisiert. Neu
+ * sind dabei [HpsCode.sendReversal] (Storno nachschicken, siehe
+ * `payments.ts`) und die Schreibweise: TECS fuehrt `0055`, das Terminal
+ * sendet `55` -- [normalizeHpsCode] macht beides zu einem Code.
+ *
+ * **Einen neuen Code aufnehmen:** Eintrag hier oder in `tecs-codes.ts`,
+ * derselbe im Dart-Zwilling, `npm run fixtures:hobex-hps-codes`; ein neuer
+ * Grund braucht in jeder Kasse eine Uebersetzung.
  */
+import { TECS_CODES } from './tecs-codes.js';
 /** Der Satz fuer den Bediener je Grund, deutsch. */
 export const HPS_REASON_HINTS = {
     approved: 'Vom Terminal genehmigt.',
+    approvedWithCondition: 'Das Terminal meldet eine Genehmigung mit Vorbehalt (etwa nur über einen Teilbetrag). Ob und in welcher Höhe belastet wurde, bitte am Terminalbeleg prüfen — nicht erneut kassieren, bevor es geklärt ist.',
     aborted: 'Der Vorgang wurde abgebrochen. Es wurde kein Geld bewegt.',
-    noCard: 'Es wurde keine Karte vorgehalten. Es wurde kein Geld bewegt — '
-        + 'bitte erneut versuchen.',
-    cardReadFailed: 'Die Karte konnte nicht gelesen werden. Es wurde kein Geld bewegt — '
-        + 'bitte erneut versuchen, notfalls die Karte stecken statt auflegen.',
-    cardDeclined: 'Die Karte wurde vom Terminal abgelehnt. Es wurde kein Geld bewegt '
-        + '— bitte eine andere Karte oder Zahlungsart verwenden.',
-    wrongPin: 'Die PIN war falsch. Es wurde kein Geld bewegt — bitte erneut '
-        + 'versuchen.',
-    amountInvalid: 'Das Terminal nimmt diesen Betrag nicht an. Es wurde kein Geld '
-        + 'bewegt.',
-    tipNotSelected: 'Das Trinkgeld wurde nicht rechtzeitig gewählt. Es wurde kein Geld '
-        + 'bewegt — bitte erneut versuchen.',
-    terminalBusy: 'Das Terminal ist noch mit einem anderen Vorgang beschäftigt. Es '
-        + 'wurde kein Geld bewegt — kurz warten und erneut versuchen.',
-    terminalBlocked: 'Das Terminal ist gesperrt. Es wurde kein Geld bewegt — bitte hobex '
-        + 'kontaktieren.',
-    terminalSetup: 'Das Terminal ist nicht richtig eingerichtet. Es wurde kein Geld '
-        + 'bewegt — bitte die Terminal-ID in den Einstellungen prüfen, sonst '
-        + 'hobex kontaktieren.',
-    terminalFault: 'Das Terminal meldet eine Störung. Es wurde kein Geld bewegt — '
-        + 'bitte das Terminal neu starten und erneut versuchen.',
-    requestRejected: 'Das Terminal hat die Anfrage abgewiesen. Es wurde kein Geld bewegt '
-        + '— tritt das wieder auf, bitte den Support kontaktieren.',
-    invalidTransaction: 'Das Terminal kennt die ursprüngliche Zahlung nicht. Es wurde kein '
-        + 'Geld bewegt.',
-    refundPassword: 'Das Passwort für die Gutschrift war falsch oder wurde nicht '
-        + 'eingegeben. Es wurde nichts ausgezahlt.',
-    refundDisabled: 'Gutschriften sind an diesem Terminal abgeschaltet. Es wurde nichts '
-        + 'ausgezahlt — bitte hobex kontaktieren.',
-    hostTimeoutReversed: 'hobex hat nicht rechtzeitig geantwortet, das Terminal hat den '
-        + 'Vorgang selbst storniert. Es wird kein Geld bewegt — bitte erneut '
-        + 'versuchen.',
-    hostFault: 'Die Verbindung zwischen Terminal und hobex ist gestört. Ob die '
-        + 'Karte belastet wurde, weiß das Terminal nicht — bitte nicht erneut '
-        + 'kassieren, bevor es geklärt ist.',
-    internalError: 'Das Terminal meldet einen internen Fehler. Ob die Karte belastet '
-        + 'wurde, ist unklar — bitte nicht erneut kassieren, bevor es geklärt '
-        + 'ist.',
+    noCard: 'Es wurde keine Karte vorgehalten. Es wurde kein Geld bewegt — bitte erneut versuchen.',
+    cardReadFailed: 'Die Karte konnte nicht gelesen werden. Es wurde kein Geld bewegt — bitte erneut versuchen, notfalls die Karte stecken statt auflegen.',
+    cardDeclined: 'Die Karte wurde vom Terminal abgelehnt. Es wurde kein Geld bewegt — bitte eine andere Karte oder Zahlungsart verwenden.',
+    issuerDeclined: 'Die Zahlung wurde von der Bank abgelehnt. Es wurde kein Geld bewegt — bitte eine andere Karte oder Zahlungsart verwenden.',
+    cardBlocked: 'Die Karte ist gesperrt. Es wurde kein Geld bewegt — bitte eine andere Karte oder Zahlungsart verwenden.',
+    cardExpired: 'Die Karte ist abgelaufen. Es wurde kein Geld bewegt — bitte eine andere Karte oder Zahlungsart verwenden.',
+    insufficientFunds: 'Das Konto ist nicht gedeckt oder das Kartenlimit ist erreicht. Es wurde kein Geld bewegt — bitte eine andere Karte oder Zahlungsart verwenden.',
+    wrongPin: 'Die PIN war falsch. Es wurde kein Geld bewegt — bitte erneut versuchen.',
+    pinTriesExceeded: 'Die PIN wurde zu oft falsch eingegeben. Es wurde kein Geld bewegt — bitte eine andere Karte oder Zahlungsart verwenden.',
+    pinRequired: 'Die Bank verlangt die PIN. Es wurde kein Geld bewegt — bitte erneut versuchen, die Karte stecken und die PIN eingeben.',
+    amountInvalid: 'Das Terminal nimmt diesen Betrag nicht an. Es wurde kein Geld bewegt.',
+    tipNotSelected: 'Das Trinkgeld wurde nicht rechtzeitig gewählt. Es wurde kein Geld bewegt — bitte erneut versuchen.',
+    terminalBusy: 'Das Terminal ist noch mit einem anderen Vorgang beschäftigt. Es wurde kein Geld bewegt — kurz warten und erneut versuchen.',
+    terminalBlocked: 'Das Terminal ist gesperrt. Es wurde kein Geld bewegt — bitte hobex kontaktieren.',
+    terminalSetup: 'Das Terminal ist nicht richtig eingerichtet. Es wurde kein Geld bewegt — bitte die Terminal-ID in den Einstellungen prüfen, sonst hobex kontaktieren.',
+    acquirerSetup: 'hobex nimmt dieses Terminal oder diesen Händler so nicht an. Es wurde kein Geld bewegt — bitte hobex kontaktieren.',
+    terminalFault: 'Das Terminal meldet eine Störung. Es wurde kein Geld bewegt — bitte das Terminal neu starten und erneut versuchen.',
+    requestRejected: 'Das Terminal hat die Anfrage abgewiesen. Es wurde kein Geld bewegt — tritt das wieder auf, bitte den Support kontaktieren.',
+    hostRejected: 'hobex hat die Zahlung abgewiesen. Es wurde kein Geld bewegt — bitte erneut versuchen; tritt das wieder auf, hobex kontaktieren.',
+    hostUnavailable: 'Die Bank oder hobex ist gerade nicht erreichbar. Es wurde kein Geld bewegt — bitte später erneut versuchen oder eine andere Zahlungsart verwenden.',
+    invalidTransaction: 'Das Terminal kennt die ursprüngliche Zahlung nicht. Es wurde kein Geld bewegt.',
+    refundPassword: 'Das Passwort für die Gutschrift war falsch oder wurde nicht eingegeben. Es wurde nichts ausgezahlt.',
+    refundDisabled: 'Gutschriften sind an diesem Terminal abgeschaltet. Es wurde nichts ausgezahlt — bitte hobex kontaktieren.',
+    refundRejected: 'Die Gutschrift wurde abgewiesen (Betrag zu hoch, bereits erstattet oder zu viele Versuche). Es wurde nichts ausgezahlt.',
+    hostTimeoutReversed: 'hobex hat nicht rechtzeitig geantwortet, das Terminal hat den Vorgang selbst storniert. Es wird kein Geld bewegt — bitte erneut versuchen.',
+    reversedByHost: 'Die Zahlung wurde wegen einer Störung automatisch storniert. Es wurde kein Geld bewegt — bitte erneut versuchen.',
+    voidedAfterHostFault: 'hobex hat nicht sauber geantwortet, die Zahlung wurde deshalb sicherheitshalber storniert. Es wurde kein Geld bewegt — bitte erneut versuchen.',
+    hostFault: 'Die Verbindung zwischen Terminal und hobex ist gestört. Ob die Karte belastet wurde, weiß das Terminal nicht — bitte nicht erneut kassieren, bevor es geklärt ist.',
+    hostTimeout: 'hobex hat nicht rechtzeitig geantwortet. Ob die Karte belastet wurde, weiß das Terminal nicht — bitte nicht erneut kassieren, bevor es geklärt ist.',
+    internalError: 'Das Terminal meldet einen internen Fehler. Ob die Karte belastet wurde, ist unklar — bitte nicht erneut kassieren, bevor es geklärt ist.',
     canceled: 'Die Zahlung ist aufgehoben.',
-    notAbortable: 'Der Vorgang ist bereits abgeschlossen und lässt sich nicht mehr '
-        + 'abbrechen.',
+    cancelDenied: 'Die Zahlung lässt sich nicht mehr aufheben und bleibt belastet — bitte stattdessen eine Gutschrift ausführen.',
+    originalDeclined: 'Die ursprüngliche Zahlung war abgelehnt; es gibt nichts aufzuheben.',
+    notAbortable: 'Der Vorgang ist bereits abgeschlossen und lässt sich nicht mehr abbrechen.',
     noStatement: 'Das Terminal hat zu diesem Vorgang keine Auskunft.',
-    technicalError: 'Das Terminal meldet einen technischen Fehler; über den Vorgang '
-        + 'sagt das nichts.',
+    technicalError: 'Das Terminal meldet einen technischen Fehler; über den Vorgang sagt das nichts.',
     unknown: 'Das Terminal nennt einen Code, dessen Bedeutung nicht bekannt ist.',
 };
 /**
- * Die beiden Gruende hinter einem Code mit `effect: 'hostUncertain'`: ob Geld
- * geflossen ist, weiss das Terminal nicht.
+ * Die Gruende hinter einem Code mit `effect: 'hostUncertain'`: ob (und wie
+ * viel) Geld geflossen ist, weiss das Terminal nicht.
  */
 export function isHostUncertainReason(reason) {
-    return reason === 'hostFault' || reason === 'internalError';
+    return reason === 'approvedWithCondition'
+        || reason === 'hostFault'
+        || reason === 'hostTimeout'
+        || reason === 'internalError';
 }
-function code(c, title, meaning, effect, reason, source, rejectsRequest = false) {
-    return { code: c, title, meaning, conclusive: effect === 'conclusive', effect, reason, source, rejectsRequest };
+function code(c, title, meaning, effect, reason, source, rejectsRequest = false, extra = {}) {
+    return {
+        code: c,
+        title,
+        meaning,
+        conclusive: effect === 'conclusive',
+        effect,
+        reason,
+        source,
+        rejectsRequest,
+        sendReversal: extra.sendReversal ?? false,
+        tecsTitle: extra.tecsTitle ?? null,
+    };
 }
 /**
  * Die vollstaendige Codetabelle — Vertrag mit dem Dart-Zwilling
@@ -109,19 +127,20 @@ function code(c, title, meaning, effect, reason, source, rejectsRequest = false)
  * dokumentierten aufsteigend -- identisch mit dem Dart-Zwilling.
  */
 export const HPS_CODES = [
-    code('0', 'Authorized', 'genehmigt', 'conclusive', 'approved', 'measuredAndDocumented'),
+    code('0', 'Authorized', 'genehmigt', 'conclusive', 'approved', 'measuredAndDocumented', false, { tecsTitle: 'Approved Transaction / OK' }),
     code('9002', 'Invalid Transaction', 'ungueltiger Vorgang -- das Terminal hat den Vorgang selbst als '
-        + 'unzulaessig verworfen, bevor irgendetwas in Bewegung kam', 'conclusive', 'invalidTransaction', 'measured', true),
+        + 'unzulaessig verworfen, bevor irgendetwas in Bewegung kam', 'conclusive', 'invalidTransaction', 'measuredAndDocumented', true, { tecsTitle: 'Invalid Transaction' }),
     code('9011', 'Transaction Canceled', 'aufgehoben ("Transaction Canceled") -- der Vorgang unter dieser '
-        + 'Kennung wurde storniert', 'conclusive', 'canceled', 'measured'),
+        + 'Kennung wurde storniert', 'conclusive', 'canceled', 'measuredAndDocumented', false, { tecsTitle: 'Transaction cancelled' }),
     code('9027', 'Original Tx not found', 'keine Aussage -- steht gleichermassen fuer "nie gesehen", "laeuft '
-        + 'gerade", "Karte nicht aufgelegt" und "abgebrochen"', 'noStatement', 'noStatement', 'measured'),
+        + 'gerade", "Karte nicht aufgelegt" und "abgebrochen"', 'noStatement', 'noStatement', 'measuredAndDocumented', false, { tecsTitle: 'Original Transaction not found' }),
     code('9900', 'Technical Error Database', '"Technical Error Database" -- gemessen im Zusammenhang mit einer '
-        + 'nicht rein numerischen Kennung; keine Aussage ueber den Vorgang '
-        + 'selbst', 'noStatement', 'technicalError', 'measured'),
+        + 'nicht rein numerischen Kennung, NACHDEM die Karte verarbeitet war; '
+        + 'laut TECS ein Datenbankfehler im Backend -- ob belastet wurde, ist '
+        + 'offen', 'hostUncertain', 'internalError', 'measuredAndDocumented', false, { tecsTitle: 'Technical Error: Database (General)' }),
     code('9003', 'Invalid Amount', '"Invalid Amount" -- der Betrag wird abgewiesen, BEVOR eine Karte '
         + 'verlangt wird (28.08.2026: 99999,99 EUR, Antwort nach 15,7 s ohne '
-        + 'Kartenaufforderung); nichts belastet', 'conclusive', 'amountInvalid', 'measured'),
+        + 'Kartenaufforderung); nichts belastet', 'conclusive', 'amountInvalid', 'measuredAndDocumented', false, { tecsTitle: 'Invalid Amount' }),
     code('100002', 'Aborted', 'abgebrochen ("Aborted") -- ueber die Kasse oder am Terminal; '
         + 'nichts belastet', 'conclusive', 'aborted', 'measuredAndDocumented'),
     code('100003', 'Card not present', 'Karte nicht aufgelegt ("Card not present") -- innerhalb der Frist '
@@ -136,7 +155,7 @@ export const HPS_CODES = [
         + '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', 'wrongPin', 'measured'),
+        + 'eine Host-Ablehnung bleibt am Terminal abrufbar; nichts belastet', 'conclusive', 'wrongPin', 'measuredAndDocumented', false, { tecsTitle: 'Incorrect PIN' }),
     // ---- ab hier: Antwortcodeliste von hobex, erhalten 11.09.2026 ----
     code('100001', 'Bad Request', 'fehlerhafte Anfrage der Kasse ("Bad Request") -- Abweisung vor dem '
         + 'Kartenfluss; nichts belastet', 'conclusive', 'requestRejected', 'documented', true),
@@ -148,10 +167,10 @@ export const HPS_CODES = [
         + 'Betrieb danach dauerhaft 9027; nichts belastet', 'conclusive', 'cardReadFailed', 'documented'),
     code('100006', 'Communication with TecsXml failed', 'keine Verbindung zum hobex-Host ("Communication with TecsXml '
         + 'failed") -- das Terminal storniert NICHT selbst; ob beim Host '
-        + 'etwas angekommen ist, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+        + 'etwas angekommen ist, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented', false, { sendReversal: true }),
     code('100007', 'Processing of TecsXml step failed', 'Schritt beim hobex-Host gescheitert ("Processing of TecsXml step '
         + 'failed") -- das Terminal storniert NICHT selbst; ob beim Host '
-        + 'belastet wurde, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+        + 'belastet wurde, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented', false, { sendReversal: true }),
     code('100008', 'Invalid TID', 'Terminal-Kennung passt nicht ("Invalid TID") -- die TID der '
         + 'Anfrage ist nicht die eingerichtete; Abweisung vor dem '
         + 'Kartenfluss, nichts belastet (am Geraet gemessen wurde dafuer '
@@ -184,18 +203,18 @@ export const HPS_CODES = [
         + 'IN_OPERATION; nichts belastet', 'conclusive', 'terminalBlocked', 'documented', true),
     code('100023', 'Invalid message type', 'ungueltige Antwort des hobex-Hosts ("Invalid message type") -- '
         + 'Nachricht und Antwortcode in den UserData ungueltig; ob beim Host '
-        + 'belastet wurde, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+        + 'belastet wurde, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented', false, { sendReversal: true }),
     code('100024', 'Transaction completion has failed', 'Abschluss des Online-Vorgangs gescheitert ("Transaction completion '
         + 'has failed") -- NACH der Anfrage beim Host; ob belastet bleibt, '
-        + 'weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+        + 'weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented', false, { sendReversal: true }),
     code('100025', 'Refund transactions are disabled', 'Gutschriften abgeschaltet ("Refund transactions are disabled") -- '
         + 'in der Geraeteeinstellung; nichts ausgezahlt', 'conclusive', 'refundDisabled', 'documented'),
     code('100026', 'Transaction was declined.', 'Host-Antwort passt nicht zur Karte ("Transaction was declined.") '
         + '-- Chip-Daten fuer eine Karte ohne Chip; das Terminal lehnt ab, ob '
-        + 'der Host zuvor belastet hat, ist offen', 'hostUncertain', 'hostFault', 'documented'),
+        + 'der Host zuvor belastet hat, ist offen', 'hostUncertain', 'hostFault', 'documented', false, { sendReversal: true }),
     code('100027', 'Unsupported UserData in TecsXml Response', 'unbekannte Daten in der Antwort des hobex-Hosts ("Unsupported '
         + 'UserData in TecsXml Response") -- ob beim Host belastet wurde, '
-        + 'weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+        + 'weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented', false, { sendReversal: true }),
     code('100028', 'Tip selection process has failed.', 'Trinkgeld nicht gewaehlt ("Tip selection process has failed.") -- '
         + 'nicht innerhalb der Frist; nichts belastet', 'conclusive', 'tipNotSelected', 'documented'),
     code('100029', 'Communication with TecsXml timeout', 'Zeitueberschreitung zum hobex-Host ("Communication with TecsXml '
@@ -207,6 +226,7 @@ export const HPS_CODES = [
     code('100999', 'Internal Error', 'interner Fehler des Terminals ("Internal Error") -- Sammelcode '
         + 'fuer jeden sonst nicht benannten Fehler, an jeder Stelle des '
         + 'Ablaufs moeglich; ob belastet wurde, ist offen', 'hostUncertain', 'internalError', 'documented'),
+    ...TECS_CODES,
 ];
 /**
  * @deprecated Seit 0.10.0 [HPS_CODES] -- die Tabelle fuehrt nicht mehr nur
@@ -328,9 +348,38 @@ export const TERMINAL_BUSY_HTTP_STATUS = 409;
  */
 export const NOT_FOUND_HTTP_STATUS = 404;
 const CODE_BY_ID = new Map(HPS_CODES.map((c) => [c.code, c]));
-/** Der Eintrag zu [code] in [HPS_CODES], oder `undefined`, wenn seine Bedeutung nicht feststeht. */
+const PLATZHALTER = 'xx';
+/** Eintraege, die eine ganze Familie abdecken (`81xx`), nach ihrem Praefix. */
+const CODE_BY_PREFIX = new Map(HPS_CODES.filter((c) => c.code.endsWith(PLATZHALTER)).map((c) => [c.code.slice(0, -PLATZHALTER.length), c]));
+/**
+ * Die Schreibweise, unter der [code] in [HPS_CODES] steht: ein rein
+ * numerischer Code ohne fuehrende Nullen (`0055` -> `55`, `0000` -> `0`),
+ * jeder andere unveraendert. Ohne diese Angleichung waere ein `0000` kein
+ * `0` -- und damit eine ABLEHNUNG einer genehmigten Zahlung.
+ * [parseHpsTransactionResponse] gleicht deshalb schon beim Einlesen an.
+ */
+export function normalizeHpsCode(code) {
+    const c = code.trim();
+    if (!/^\d+$/.test(c))
+        return c;
+    const ohneNullen = c.replace(/^0+/, '');
+    return ohneNullen === '' ? '0' : ohneNullen;
+}
+/**
+ * Der Eintrag zu [code] in [HPS_CODES], oder `undefined`, wenn seine
+ * Bedeutung nicht feststeht. Findet beide Schreibweisen
+ * ([normalizeHpsCode]) und die Familien mit Platzhalter (`8105` -> `81xx`).
+ */
 export function hpsCodeInfo(code) {
-    return code === undefined ? undefined : CODE_BY_ID.get(code);
+    if (code === undefined)
+        return undefined;
+    const c = normalizeHpsCode(code);
+    const genau = CODE_BY_ID.get(c);
+    if (genau)
+        return genau;
+    if (c.length === 4 && /^\d+$/.test(c))
+        return CODE_BY_PREFIX.get(c.slice(0, 2));
+    return undefined;
 }
 /**
  * Der Grund zu [code] -- `'unknown'` fuer einen Code ausserhalb der Tabelle,
@@ -374,7 +423,7 @@ export function parseHpsTransactionResponse(raw) {
         // responseCode kommt teils als Zahl, teils als Zeichenkette — siehe
         // Zwilling. Ein leerer String traegt keine Aussage und wird wie ein
         // fehlendes Feld behandelt.
-        responseCode: nonEmpty(stringify(r['responseCode'])),
+        responseCode: normalizedCode(stringify(r['responseCode'])),
         responseText: asString(r['responseText']),
         state: asString(r['state']),
         raw: r,
@@ -404,6 +453,14 @@ function stringify(v) {
 function nonEmpty(v) {
     return v === undefined || v === '' ? undefined : v;
 }
+/**
+ * Der Ergebniscode in der Schreibweise der Tabelle ([normalizeHpsCode]):
+ * `0000` wird `0`. Der Rumpf in `raw` bleibt unveraendert.
+ */
+function normalizedCode(v) {
+    const c = nonEmpty(v?.trim());
+    return c === undefined ? undefined : normalizeHpsCode(c);
+}
 /** `true`, wenn der Vorgang genehmigt ist. */
 export function isApproved(res) {
     return res.responseCode === APPROVED_CODE;
@@ -426,7 +483,10 @@ export function isNotAbortable(res) {
 export function isNoStatement(res) {
     return res.responseCode === NO_STATEMENT_CODE;
 }
-/** `true`, wenn das Terminal einen technischen Fehler meldet (9900). */
+/**
+ * `true`, wenn das Terminal einen technischen Fehler meldet (9900). Seit der
+ * TECS-Liste zugleich [isHostUncertain]: ob belastet wurde, ist offen.
+ */
 export function isTechnicalError(res) {
     return res.responseCode === TECHNICAL_ERROR_CODE;
 }
@@ -470,6 +530,14 @@ export function isConclusiveAsStatus(res) {
 export function isHostUncertain(res) {
     return hpsCodeInfo(res.responseCode)?.effect === 'hostUncertain';
 }
+/**
+ * `true`, wenn zu diesem Code ein Storno nachzuschicken ist
+ * ([HpsCode.sendReversal]) -- der Host hat nicht oder nicht brauchbar
+ * geantwortet, etwa `9908`.
+ */
+export function needsReversal(res) {
+    return hpsCodeInfo(res.responseCode)?.sendReversal ?? false;
+}
 /**
  * `true`, wenn ein Ergebniscode VORHANDEN ist, dessen Bedeutung aber nicht
  * feststeht -- er fehlt in [HPS_CODES]. Ein Code, den dieses Modell schlicht

package/dist/esm/rechnung/texte.d.ts

@@ -40,11 +40,12 @@ declare const DE: {
     readonly 'pdf.summe.gesamt.rechnung': "Gesamtbetrag";
     readonly 'pdf.summe.gesamt.gutschrift': "Gutschriftsbetrag";
     readonly 'steuer.kleinunternehmer': "Gemäß § 6 Abs. 1 Z 27 UStG wird keine Umsatzsteuer verrechnet (Kleinunternehmer).";
-    readonly 'steuer.igLieferung': "Steuerfreie innergemeinschaftliche Lieferung (Art. 6 Abs. 1 UStG).";
+    readonly 'steuer.igLieferung.titel': "Steuerfreie innergemeinschaftliche Lieferung. ";
+    readonly 'steuer.igLieferung.text': "Gemäß Art. 6 Abs. 1 UStG (Art. 138 MwSt-RL 2006/112/EG). Die Erwerbsbesteuerung erfolgt durch den Abnehmer im Bestimmungsland.";
     readonly 'steuer.ausfuhr': "Steuerfreie Ausfuhrlieferung (§ 6 Abs. 1 Z 1 UStG).";
-    readonly 'steuer.reverseCharge.titel': "Steuerfreie Leistung – Reverse Charge. ";
-    readonly 'steuer.reverseCharge.text': "Übergang der Steuerschuldnerschaft auf den Leistungsempfänger gem. Art. 196 MwSt-RL 2006/112/EG (innergemeinschaftliche Leistung). Die Umsatzsteuer ist vom Leistungsempfänger im Bestimmungsland abzuführen.";
-    readonly 'steuer.reverseCharge.uid': "UID Leistungserbringer: {verkaeufer}   ·   UID Leistungsempfänger: {kaeufer}";
+    readonly 'steuer.reverseCharge.titel': "Steuerschuldnerschaft des Leistungsempfängers. ";
+    readonly 'steuer.reverseCharge.text': "Übergang der Steuerschuld gem. Art. 196 MwSt-RL 2006/112/EG (innergemeinschaftliche Leistung). Die Leistung ist nicht steuerfrei — die Umsatzsteuer schuldet und entrichtet der Leistungsempfänger in seinem Land.";
+    readonly 'steuer.uidZeile': "UID Leistungserbringer: {verkaeufer}   ·   UID Leistungsempfänger: {kaeufer}";
     readonly 'pdf.zahlung.titel': "ZAHLUNGSINFORMATIONEN";
     readonly 'pdf.zahlung.empfaenger': "Empfänger";
     readonly 'pdf.zahlung.iban': "IBAN";

package/dist/esm/rechnung/texte.js

@@ -25,11 +25,18 @@ const DE = {
     'pdf.summe.gesamt.rechnung': 'Gesamtbetrag',
     'pdf.summe.gesamt.gutschrift': 'Gutschriftsbetrag',
     'steuer.kleinunternehmer': 'Gemäß § 6 Abs. 1 Z 27 UStG wird keine Umsatzsteuer verrechnet (Kleinunternehmer).',
-    'steuer.igLieferung': 'Steuerfreie innergemeinschaftliche Lieferung (Art. 6 Abs. 1 UStG).',
+    'steuer.igLieferung.titel': 'Steuerfreie innergemeinschaftliche Lieferung. ',
+    'steuer.igLieferung.text': 'Gemäß Art. 6 Abs. 1 UStG (Art. 138 MwSt-RL 2006/112/EG). Die Erwerbsbesteuerung erfolgt durch den Abnehmer im Bestimmungsland.',
     'steuer.ausfuhr': 'Steuerfreie Ausfuhrlieferung (§ 6 Abs. 1 Z 1 UStG).',
-    'steuer.reverseCharge.titel': 'Steuerfreie Leistung – Reverse Charge. ',
-    'steuer.reverseCharge.text': 'Übergang der Steuerschuldnerschaft auf den Leistungsempfänger gem. Art. 196 MwSt-RL 2006/112/EG (innergemeinschaftliche Leistung). Die Umsatzsteuer ist vom Leistungsempfänger im Bestimmungsland abzuführen.',
-    'steuer.reverseCharge.uid': 'UID Leistungserbringer: {verkaeufer}   ·   UID Leistungsempfänger: {kaeufer}',
+    // Reverse Charge ist KEINE Steuerbefreiung: der Umsatz bleibt steuerpflichtig,
+    // nur die Steuer schuldet der Empfaenger (§ 11 Abs. 1a UStG; der Begriff steht
+    // wortgleich in Art. 226 Nr. 11a MwSt-RL). „Steuerfrei" waere sachlich falsch
+    // und erbraechte den vorgeschriebenen Hinweis nicht.
+    'steuer.reverseCharge.titel': 'Steuerschuldnerschaft des Leistungsempfängers. ',
+    'steuer.reverseCharge.text': 'Übergang der Steuerschuld gem. Art. 196 MwSt-RL 2006/112/EG (innergemeinschaftliche Leistung). Die Leistung ist nicht steuerfrei — die Umsatzsteuer schuldet und entrichtet der Leistungsempfänger in seinem Land.',
+    // Beide UID-Nummern: bei Reverse Charge § 11 Abs. 1a, bei der ig. Lieferung
+    // Art. 11 Abs. 2 UStG.
+    'steuer.uidZeile': 'UID Leistungserbringer: {verkaeufer}   ·   UID Leistungsempfänger: {kaeufer}',
     'pdf.zahlung.titel': 'ZAHLUNGSINFORMATIONEN',
     'pdf.zahlung.empfaenger': 'Empfänger',
     'pdf.zahlung.iban': 'IBAN',
@@ -207,11 +214,12 @@ const EN = {
     'pdf.summe.gesamt.rechnung': 'Total',
     'pdf.summe.gesamt.gutschrift': 'Credit total',
     'steuer.kleinunternehmer': 'No VAT charged pursuant to § 6 (1) no. 27 UStG (small business exemption).',
-    'steuer.igLieferung': 'VAT-exempt intra-Community supply (Art. 6 (1) UStG).',
+    'steuer.igLieferung.titel': 'VAT-exempt intra-Community supply. ',
+    'steuer.igLieferung.text': 'Pursuant to Art. 6 (1) UStG (Art. 138 of VAT Directive 2006/112/EC). The acquisition is taxed by the customer in the country of destination.',
     'steuer.ausfuhr': 'VAT-exempt export delivery (§ 6 (1) no. 1 UStG).',
-    'steuer.reverseCharge.titel': 'VAT-exempt service – reverse charge. ',
-    'steuer.reverseCharge.text': 'VAT liability transferred to the recipient pursuant to Art. 196 of VAT Directive 2006/112/EC (intra-Community service). VAT is to be accounted for by the recipient in the country of destination.',
-    'steuer.reverseCharge.uid': 'VAT ID supplier: {verkaeufer}   ·   VAT ID recipient: {kaeufer}',
+    'steuer.reverseCharge.titel': 'Reverse charge – VAT liability of the recipient. ',
+    'steuer.reverseCharge.text': 'VAT liability transferred pursuant to Art. 196 of VAT Directive 2006/112/EC (intra-Community service). The service is not VAT-exempt — the recipient owes and accounts for the VAT in their country.',
+    'steuer.uidZeile': 'VAT ID supplier: {verkaeufer}   ·   VAT ID recipient: {kaeufer}',
     'pdf.zahlung.titel': 'PAYMENT DETAILS',
     'pdf.zahlung.empfaenger': 'Payee',
     'pdf.zahlung.iban': 'IBAN',

package/dist/esm/rechnung/typen.d.ts

@@ -118,6 +118,13 @@ export interface PaymentInput {
     paidAt?: string;
     /** Zahlungskennung des Fremdsystems — gespeichert, aber nicht gedruckt. */
     reference?: string;
+    /**
+     * Die Zahlung erfolgte vor Ort beim Unternehmer (Terminal an der Kasse).
+     * Dann ist sie ein Barumsatz — auch mit Karte (§ 131b Abs. 1 Z 3 UStG) — und
+     * die Antwort traegt den Hinweis `cash_receipt_required`. Zu `transfer`
+     * passt das Kennzeichen nicht und wird abgewiesen.
+     */
+    onSite?: boolean;
 }
 export interface RecordPaymentRequest extends PaymentInput {
     /** Pflicht: ohne ihn bucht eine Wiederholung eine zweite Zahlung. */

package/dist/esm/rechnung/vertrag.d.ts

@@ -52,10 +52,13 @@ export type EInvoiceFormat = (typeof EINVOICE_FORMATS)[number];
 export declare const INVOICE_LANGUAGES: readonly ["de", "en"];
 export type InvoiceLanguage = (typeof INVOICE_LANGUAGES)[number];
 /**
- * Wie eine Rechnung bezahlt wurde. Der Vermerk ist Buchhaltung, kein Beleg:
- * `cash` wird gebucht, die Antwort traegt dann zusaetzlich den Hinweis
- * `cash_receipt_required` — eine Barzahlung ist ein Barumsatz und braucht
- * einen Beleg (§ 132a BAO), bei Registrierkassenpflicht ueber die Kasse.
+ * Wie eine Rechnung bezahlt wurde. Der Vermerk ist Buchhaltung, kein Beleg.
+ *
+ * Ein **Barumsatz** ist nicht nur Bargeld: als Barzahlung gilt auch die Zahlung
+ * mit Bankomat- oder Kreditkarte **vor Ort** (§ 131b Abs. 1 Z 3 UStG), nicht
+ * aber dieselbe Karte im Internet. Weil `card` und `online` beides sein
+ * koennen, sagt das Feld `onSite` es dem Server — und nur dann traegt die
+ * Antwort den Hinweis `cash_receipt_required` (bei `cash` immer).
  */
 export declare const INVOICE_PAYMENT_METHODS: readonly ["transfer", "card", "online", "cash"];
 export type InvoicePaymentMethod = (typeof INVOICE_PAYMENT_METHODS)[number];

package/dist/esm/rechnung/vertrag.js

@@ -84,10 +84,13 @@ export const EINVOICE_FORMATS = ['ubl', 'cii'];
  */
 export const INVOICE_LANGUAGES = ['de', 'en'];
 /**
- * Wie eine Rechnung bezahlt wurde. Der Vermerk ist Buchhaltung, kein Beleg:
- * `cash` wird gebucht, die Antwort traegt dann zusaetzlich den Hinweis
- * `cash_receipt_required` — eine Barzahlung ist ein Barumsatz und braucht
- * einen Beleg (§ 132a BAO), bei Registrierkassenpflicht ueber die Kasse.
+ * Wie eine Rechnung bezahlt wurde. Der Vermerk ist Buchhaltung, kein Beleg.
+ *
+ * Ein **Barumsatz** ist nicht nur Bargeld: als Barzahlung gilt auch die Zahlung
+ * mit Bankomat- oder Kreditkarte **vor Ort** (§ 131b Abs. 1 Z 3 UStG), nicht
+ * aber dieselbe Karte im Internet. Weil `card` und `online` beides sein
+ * koennen, sagt das Feld `onSite` es dem Server — und nur dann traegt die
+ * Antwort den Hinweis `cash_receipt_required` (bei `cash` immer).
  */
 export const INVOICE_PAYMENT_METHODS = ['transfer', 'card', 'online', 'cash'];
 /**
@@ -288,6 +291,12 @@ export const PAYMENT_FELDER = Object.freeze({
     amountCents: { typ: 'integer', pflicht: false, min: 1, max: 100_000_000 },
     paidAt: datum(),
     reference: text(100),
+    /**
+     * Die Zahlung erfolgte **vor Ort** beim Unternehmer (Terminal an der Kasse,
+     * Zahlung per App am Tresen). Dann ist sie ein Barumsatz. Zu `transfer` passt
+     * das nicht — eine Ueberweisung erfolgt nie vor Ort — und wird abgewiesen.
+     */
+    onSite: { typ: 'boolean', pflicht: false },
 });
 export const RECHNUNG_ANFRAGEN = Object.freeze({
     createCustomer: {
@@ -381,6 +390,7 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
         amountCents: { typ: 'integer', pflicht: false, min: 1, max: 100_000_000 },
         paidAt: datum(),
         reference: text(100),
+        onSite: { typ: 'boolean', pflicht: false },
     },
 });
 /** Genau eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */