@kreiseck/kasseneck-api 0.17.0 → 0.19.0

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/api.d.ts

@@ -6,7 +6,7 @@
  */
 import { type FetchLike } from '../client/transport.js';
 import type { EInvoiceFormat, InvoiceLanguage } from './vertrag.js';
-import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult } from './typen.js';
+import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult, RecordPaymentRequest, RecordPaymentResult } from './typen.js';
 export interface RechnungApiOptions {
     /** `api_key` des Kontos (`kr_live_…` / `kr_test_…`). Gehoert auf einen Server. */
     apiKey: string;
@@ -37,6 +37,8 @@ export interface RechnungApi {
         number: string;
     }): Promise<InvoiceDetail>;
     listInvoices(abfrage?: InvoiceListQuery): Promise<InvoicePage>;
+    /** Eine spaeter eingetroffene Zahlung nachtragen; `idempotencyKey` ist Pflicht. */
+    recordInvoicePayment(anfrage: RecordPaymentRequest): Promise<RecordPaymentResult>;
     /** Mit `language` ungleich der Rechnungssprache: gekennzeichnete Uebersetzungskopie. */
     getInvoicePdf(invoiceId: string, optionen?: {
         language?: InvoiceLanguage;

package/dist/esm/rechnung/api.js

@@ -6,7 +6,7 @@
  */
 import { createBinaryTransport, createTransport } from '../client/transport.js';
 import { rechnungKeyAuth } from './auth.js';
-import { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, searchCustomers, updateCustomer, } from './endpunkte.js';
+import { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
 export function createRechnungApi(optionen) {
     const transportOptionen = {
         auth: rechnungKeyAuth({ apiKey: optionen.apiKey }),
@@ -29,6 +29,7 @@ export function createRechnungApi(optionen) {
         getInvoicePdf: (id, o) => getInvoicePdf(rufenBinaer, id, o),
         getInvoiceXml: (id, format) => getInvoiceXml(rufen, id, format),
         getInvoiceSetupStatus: () => getInvoiceSetupStatus(rufen),
+        recordInvoicePayment: (anfrage) => recordInvoicePayment(rufen, anfrage),
         listBrands: () => listBrands(rufen),
     };
 }

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

@@ -18,7 +18,7 @@
  */
 import type { InternerBinaerTransport, InternerTransport } from '../client/aufrufe.js';
 import type { EInvoiceFormat, InvoiceLanguage } from './vertrag.js';
-import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult } from './typen.js';
+import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult, RecordPaymentRequest, RecordPaymentResult } from './typen.js';
 export declare function createCustomer(rufen: InternerTransport, customer: CustomerInput, optionen?: {
     idempotencyKey?: string;
 }): Promise<Customer>;
@@ -53,6 +53,16 @@ export declare function getInvoiceSetupStatus(rufen: InternerTransport): Promise
 export declare function getInvoicePdf(rufenBinaer: InternerBinaerTransport, invoiceId: string, optionen?: {
     language?: InvoiceLanguage;
 }): Promise<Uint8Array>;
+/**
+ * Eine Zahlung nachtragen, die nach dem Ausstellen eingetroffen ist
+ * (Ueberweisung, Teilzahlung). Der `idempotencyKey` ist Pflicht: ohne ihn
+ * bucht ein Wiederholungslauf nach einem Zeitlimit eine zweite Zahlung.
+ *
+ * Bei `method: 'cash'` wird die Zahlung gebucht und die Antwort traegt
+ * zusaetzlich `notice` — eine Barzahlung ist ein Barumsatz und braucht einen
+ * Beleg (§ 132a BAO), den dieser Vermerk nicht ersetzt.
+ */
+export declare function recordInvoicePayment(rufen: InternerTransport, anfrage: RecordPaymentRequest): Promise<RecordPaymentResult>;
 /** Die Marken des Kontos — die Kennung geht als `brandId` in `issueInvoice`. */
 export declare function listBrands(rufen: InternerTransport): Promise<Brand[]>;
 /**

package/dist/esm/rechnung/endpunkte.js

@@ -126,6 +126,27 @@ export function getInvoicePdf(rufenBinaer, invoiceId, optionen = {}) {
         params['language'] = optionen.language;
     return rufenBinaer('getInvoicePdf', params);
 }
+/**
+ * Eine Zahlung nachtragen, die nach dem Ausstellen eingetroffen ist
+ * (Ueberweisung, Teilzahlung). Der `idempotencyKey` ist Pflicht: ohne ihn
+ * bucht ein Wiederholungslauf nach einem Zeitlimit eine zweite Zahlung.
+ *
+ * Bei `method: 'cash'` wird die Zahlung gebucht und die Antwort traegt
+ * zusaetzlich `notice` — eine Barzahlung ist ein Barumsatz und braucht einen
+ * Beleg (§ 132a BAO), den dieser Vermerk nicht ersetzt.
+ */
+export async function recordInvoicePayment(rufen, anfrage) {
+    const daten = await rufen('recordInvoicePayment', nutzlast(anfrage));
+    const roh = objekt(daten);
+    const ergebnis = {
+        invoice: pflichtObjekt('recordInvoicePayment', daten, 'invoice'),
+        payment: pflichtObjekt('recordInvoicePayment', daten, 'payment'),
+        replayed: roh['replayed'] === true,
+    };
+    if (roh['notice'])
+        ergebnis.notice = roh['notice'];
+    return ergebnis;
+}
 /** Die Marken des Kontos — die Kennung geht als `brandId` in `issueInvoice`. */
 export async function listBrands(rufen) {
     const brands = objekt(await rufen('listBrands', {}))['brands'];

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

@@ -13,7 +13,7 @@
 export { createRechnungApi, type RechnungApi, type RechnungApiOptions } from './api.js';
 export { rechnungKeyAuth, type RechnungKeyAuthOptions } from './auth.js';
 export { istRechnungFehler, rechnungFehlerCode, rechnungFeldFehler, type RechnungFeldFehler, } from './fehler.js';
-export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, searchCustomers, updateCustomer, } from './endpunkte.js';
-export type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, IssueInvoiceRequest, IssueResult, } from './typen.js';
+export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
+export type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, InvoiceNotice, InvoicePayment, IssueInvoiceRequest, IssueResult, PaymentInput, RecordPaymentRequest, RecordPaymentResult, } from './typen.js';
 export { RECHNUNG_TEXTE, rechnungText, type RechnungTextSchluessel } from './texte.js';
-export { RECHNUNG_VERTRAG_VERSION, RECHNUNG_AUFRUFE, INVOICE_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, INVOICE_LANGUAGES, INVOICE_UNITS, RECHNUNG_EINHEITEN_CODES, INVOICE_SETUP_REQUIREMENTS, KUNDE_FELDER, POSITION_FELDER, RECHNUNG_ANFRAGEN, RECHNUNG_GENAU_EINS, RECHNUNG_MINDESTENS_EINS, type RechnungAufruf, type InvoiceErrorCode, type CreditNoteReason, type TaxScheme, type PriceMode, type VatRatePercent, type CustomerType, type InvoiceListStatus, type DocType, type EInvoiceFormat, type InvoiceLanguage, type InvoiceUnit, type InvoiceSetupRequirement, type Format, type Feld, } from './vertrag.js';
+export { RECHNUNG_VERTRAG_VERSION, RECHNUNG_AUFRUFE, INVOICE_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, INVOICE_NOTICE_CODES, INVOICE_UNITS, RECHNUNG_EINHEITEN_CODES, INVOICE_SETUP_REQUIREMENTS, KUNDE_FELDER, POSITION_FELDER, RECHNUNG_ANFRAGEN, RECHNUNG_GENAU_EINS, RECHNUNG_MINDESTENS_EINS, type RechnungAufruf, type InvoiceErrorCode, type CreditNoteReason, type TaxScheme, type PriceMode, type VatRatePercent, type CustomerType, type InvoiceListStatus, type DocType, type EInvoiceFormat, type InvoiceLanguage, type InvoicePaymentMethod, type InvoiceNoticeCode, type InvoiceUnit, type InvoiceSetupRequirement, type Format, type Feld, } from './vertrag.js';

package/dist/esm/rechnung/index.js

@@ -13,6 +13,6 @@
 export { createRechnungApi } from './api.js';
 export { rechnungKeyAuth } from './auth.js';
 export { istRechnungFehler, rechnungFehlerCode, rechnungFeldFehler, } from './fehler.js';
-export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, searchCustomers, updateCustomer, } from './endpunkte.js';
+export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
 export { RECHNUNG_TEXTE, rechnungText } from './texte.js';
-export { RECHNUNG_VERTRAG_VERSION, RECHNUNG_AUFRUFE, INVOICE_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, INVOICE_LANGUAGES, INVOICE_UNITS, RECHNUNG_EINHEITEN_CODES, INVOICE_SETUP_REQUIREMENTS, KUNDE_FELDER, POSITION_FELDER, RECHNUNG_ANFRAGEN, RECHNUNG_GENAU_EINS, RECHNUNG_MINDESTENS_EINS, } from './vertrag.js';
+export { RECHNUNG_VERTRAG_VERSION, RECHNUNG_AUFRUFE, INVOICE_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, INVOICE_NOTICE_CODES, INVOICE_UNITS, RECHNUNG_EINHEITEN_CODES, INVOICE_SETUP_REQUIREMENTS, KUNDE_FELDER, POSITION_FELDER, RECHNUNG_ANFRAGEN, RECHNUNG_GENAU_EINS, RECHNUNG_MINDESTENS_EINS, } from './vertrag.js';

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

@@ -5,7 +5,7 @@
  * Betraege sind ueberall ganze Cent. Datumsangaben sind `YYYY-MM-DD` nach
  * Wiener Kalender.
  */
-import type { CreditNoteReason, CustomerType, DocType, InvoiceLanguage, InvoiceUnit, InvoiceSetupRequirement, InvoiceListStatus, PriceMode, TaxScheme, VatRatePercent } from './vertrag.js';
+import type { CreditNoteReason, CustomerType, DocType, InvoiceLanguage, InvoiceNoticeCode, InvoicePaymentMethod, InvoiceUnit, InvoiceSetupRequirement, InvoiceListStatus, PriceMode, TaxScheme, VatRatePercent } from './vertrag.js';
 export interface CustomerInput {
     type: CustomerType;
     name: string;
@@ -102,6 +102,49 @@ export interface IssueInvoiceRequest {
     language?: InvoiceLanguage;
     /** Marke (Kennung aus `listBrands`); sonst die Standardmarke. Unbekannt = `brand_not_found`. */
     brandId?: string;
+    /**
+     * Schon bezahlt (Shop kassiert online, Rechnung folgt). Die Zahlung entsteht
+     * in derselben Transaktion wie das Festschreiben: das PDF traegt dann keine
+     * Zahlungsinformationen und keinen Giro-QR.
+     */
+    payment?: PaymentInput;
+}
+/** Eine Zahlung, wie das Fremdsystem sie meldet. */
+export interface PaymentInput {
+    method: InvoicePaymentMethod;
+    /** Ohne Angabe der volle Bruttobetrag. */
+    amountCents?: number;
+    /** Ohne Angabe der heutige Wiener Tag; nie in der Zukunft. */
+    paidAt?: string;
+    /** Zahlungskennung des Fremdsystems — gespeichert, aber nicht gedruckt. */
+    reference?: string;
+}
+export interface RecordPaymentRequest extends PaymentInput {
+    /** Pflicht: ohne ihn bucht eine Wiederholung eine zweite Zahlung. */
+    idempotencyKey: string;
+    invoiceId: string;
+}
+/** Eine gebuchte Zahlung, wie die API sie zurueckgibt. */
+export interface InvoicePayment {
+    id: string;
+    amountCents: number;
+    paidAt: string;
+    method: InvoicePaymentMethod;
+    reference: string | null;
+}
+/**
+ * Ein Hinweis zu einer erfolgreichen Antwort — kein Fehler, sondern etwas,
+ * das der Aufrufer wissen sollte (heute nur `cash_receipt_required`).
+ */
+export interface InvoiceNotice {
+    code: InvoiceNoticeCode;
+    message: string;
+}
+export interface RecordPaymentResult {
+    invoice: Invoice;
+    payment: InvoicePayment;
+    replayed: boolean;
+    notice?: InvoiceNotice;
 }
 export interface CancelInvoiceRequest {
     idempotencyKey: string;
@@ -147,6 +190,10 @@ export interface Invoice {
         id: string | null;
         name: string | null;
     } | null;
+    /** Summe der gebuchten Zahlungen. */
+    paidCents: number;
+    /** Was noch offen ist; `0` heisst bezahlt. */
+    openCents: number;
 }
 /** Eine Marke des Kontos (Logo, Farbe, Absender) — `id` geht als `brandId` in `issueInvoice`. */
 export interface Brand {

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

@@ -18,13 +18,13 @@
  * Nummer, Summen — ist bewusst **nicht** setzbar.
  */
 export declare const RECHNUNG_VERTRAG_VERSION = 1;
-export declare const RECHNUNG_AUFRUFE: readonly ["createCustomer", "getCustomer", "updateCustomer", "searchCustomers", "issueInvoice", "cancelInvoice", "createCreditNote", "getInvoice", "listInvoices", "getInvoicePdf", "getInvoiceXml", "getInvoiceSetupStatus", "listBrands"];
+export declare const RECHNUNG_AUFRUFE: readonly ["createCustomer", "getCustomer", "updateCustomer", "searchCustomers", "issueInvoice", "cancelInvoice", "createCreditNote", "getInvoice", "listInvoices", "getInvoicePdf", "getInvoiceXml", "getInvoiceSetupStatus", "listBrands", "recordInvoicePayment"];
 export type RechnungAufruf = (typeof RECHNUNG_AUFRUFE)[number];
 /**
  * Stabile Fehlercodes. Das Fremdsystem verzweigt am Code, der Text darf sich
  * aendern. `validation` traegt zusaetzlich `errors: [{ field, message }]`.
  */
-export declare const INVOICE_ERROR_CODES: readonly ["validation", "idempotency_conflict", "module_inactive", "customer_not_found", "customer_exists", "short_code_taken", "short_code_immutable", "recipient_required", "invoice_requirements_missing", "invoice_not_found", "invoice_ambiguous", "not_cancellable", "partial_credit_exists", "credit_exceeds_invoice", "einvoice_incomplete", "invoice_api_not_enabled", "invoice_setup_incomplete", "language_not_allowed", "brand_not_found"];
+export declare const INVOICE_ERROR_CODES: readonly ["validation", "idempotency_conflict", "module_inactive", "customer_not_found", "customer_exists", "short_code_taken", "short_code_immutable", "recipient_required", "invoice_requirements_missing", "invoice_not_found", "invoice_ambiguous", "not_cancellable", "partial_credit_exists", "credit_exceeds_invoice", "einvoice_incomplete", "invoice_api_not_enabled", "invoice_setup_incomplete", "language_not_allowed", "brand_not_found", "not_payable", "payment_exceeds_invoice"];
 export type InvoiceErrorCode = (typeof INVOICE_ERROR_CODES)[number];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 export declare const CREDIT_NOTE_REASONS: readonly ["cancellation", "price_reduction", "return", "incorrect_invoice", "other"];
@@ -51,6 +51,20 @@ 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.
+ */
+export declare const INVOICE_PAYMENT_METHODS: readonly ["transfer", "card", "online", "cash"];
+export type InvoicePaymentMethod = (typeof INVOICE_PAYMENT_METHODS)[number];
+/**
+ * Hinweise, die eine erfolgreiche Antwort zusaetzlich tragen kann (`data.notice`).
+ * Sie sind keine Fehler: der Aufruf hat gewirkt, es gibt nur etwas zu wissen.
+ */
+export declare const INVOICE_NOTICE_CODES: readonly ["cash_receipt_required"];
+export type InvoiceNoticeCode = (typeof INVOICE_NOTICE_CODES)[number];
 /**
  * Einheiten einer Position. Die API nimmt nur diese Schluessel an; gedruckt
  * wird das Kuerzel in der Sprache der Rechnung (`RECHNUNG_TEXTE`,
@@ -129,6 +143,14 @@ export type Feld = {
 export declare const KUNDE_FELDER: Readonly<Record<string, Feld>>;
 /** Eine Rechnungs- oder Gutschriftsposition. Preise in ganzen Cent. */
 export declare const POSITION_FELDER: Readonly<Record<string, Feld>>;
+/**
+ * Eine Zahlung zu einer Rechnung. Ohne `amountCents` gilt der volle
+ * Bruttobetrag, ohne `paidAt` der heutige Wiener Tag. `reference` ist die
+ * Zahlungskennung des Fremdsystems (z. B. `pi_3Q...`) — sie wird gespeichert,
+ * aber **nicht gedruckt**: die Rechnung wird aufbewahrt und vervielfaeltigt,
+ * und dem Empfaenger nuetzt sie nichts.
+ */
+export declare const PAYMENT_FELDER: Readonly<Record<string, Feld>>;
 export declare const RECHNUNG_ANFRAGEN: Readonly<Record<RechnungAufruf, Readonly<Record<string, Feld>>>>;
 /** Genau eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
 export declare const RECHNUNG_GENAU_EINS: Readonly<Partial<Record<RechnungAufruf, readonly (readonly string[])[]>>>;