@kreiseck/kasseneck-api 0.28.0 → 0.30.0

package/dist/cjs/receipt/layout.js

@@ -303,16 +303,13 @@ function stripeBlock(daten, cardPaymentId) {
     return zeilen;
 }
 /**
- * Der Kartenzahlungsblock des Belegs -- fuer JEDEN Anbieter, den das Backend
- * kennt. Ohne `cardPaymentData` bleibt der Block weg; ein unbekannter Anbieter
- * ebenfalls, still und ohne Fehler: ein Beleg muss sich immer zeigen lassen.
+ * Der Kartenzahlungsblock eines Anbieters -- fuer JEDEN Anbieter, den das
+ * Backend kennt. Ein unbekannter Anbieter bekommt keinen Block, still und
+ * ohne Fehler: ein Beleg muss sich immer zeigen lassen.
  */
-function kartenblock(receipt) {
-    const daten = receipt.cardPaymentData;
-    if (daten == null)
-        return [];
+function anbieterBlock(provider, daten, id) {
     const zeilen = (() => {
-        switch (receipt.creditCardProvider) {
+        switch (provider) {
             case 'hobexHps':
             case 'hobexCloudApi':
                 return hobexBlock(daten);
@@ -324,7 +321,7 @@ function kartenblock(receipt) {
             case 'myposPro':
                 return myposBlock(daten);
             case 'stripe':
-                return stripeBlock(daten, receipt.cardPaymentId ?? null);
+                return stripeBlock(daten, id);
             default:
                 return [];
         }
@@ -337,12 +334,117 @@ function kartenblock(receipt) {
     // gehoert aber zum Blatt, nicht zum Terminal.
     return [...zeilen, { kind: 'space', lines: 1 }];
 }
+/**
+ * Die Kartenzahlungsbloecke des Belegs. Mit Zahlungsliste (`payments`) je
+ * Zahlung mit Anbieter und Terminaldaten ein Block, in Zahlungsreihenfolge --
+ * zwei Karten desselben Anbieters ergeben zwei Bloecke; die alten
+ * Einzelfelder zaehlen dann nicht. Bei mehreren Zahlungen steht vor jedem
+ * Block, nicht fett und zentriert, die Nummer der Zahlung aus der
+ * Aufschluesselung („2. Kartenzahlung") -- so ist jeder Block seiner Zeile
+ * zuzuordnen. Ohne (oder mit leerer) Liste der bisherige Weg ueber
+ * `creditCardProvider`/`cardPaymentData`/`cardPaymentId` -- ebenso bei
+ * hoechstens einer Zahlung ohne `providerData`, wenn die Altfelder gesetzt sind.
+ */
+function kartenblock(receipt) {
+    const zahlungen = receipt.payments;
+    // Eine einzelne Zahlung ohne Terminaldaten neben gesetzten Altfeldern
+    // (creditCardProvider + cardPaymentData): der bisherige Block, wie ohne Liste.
+    const altfelderTragen = zahlungen != null && zahlungen.length <= 1
+        && zahlungen.every((z) => z.providerData == null)
+        && receipt.creditCardProvider != null && receipt.cardPaymentData != null;
+    if (zahlungen != null && zahlungen.length > 0 && !altfelderTragen) {
+        const zeilen = [];
+        zahlungen.forEach((zahlung, i) => {
+            if (zahlung.provider == null || zahlung.providerData == null)
+                return;
+            const block = anbieterBlock(zahlung.provider, zahlung.providerData, zahlung.providerPaymentId ?? null);
+            if (block.length === 0)
+                return;
+            if (zahlungen.length > 1)
+                zeilen.push(textZeile(zahlungNummerText(zahlung, i), 'center'));
+            zeilen.push(...block);
+        });
+        return zeilen;
+    }
+    const daten = receipt.cardPaymentData;
+    if (daten == null)
+        return [];
+    return anbieterBlock(receipt.creditCardProvider, daten, receipt.cardPaymentId ?? null);
+}
 function zahlungsartText(wert) {
     if (wert != null && typeof wert === 'object') {
         return wert.label;
     }
     return typeof wert === 'string' ? wert : '';
 }
+/** Barzahlarten -- Zwilling von `BAR_ZAHLARTEN` (functions/gemeinsam/tip-core.js). */
+const BAR_ZAHLARTEN = ['cash', 'uberCash', 'boltCash'];
+function zahlartSchluessel(wert) {
+    if (wert != null && typeof wert === 'object')
+        return wert.value;
+    return typeof wert === 'string' ? wert : '';
+}
+/**
+ * Nummerierter Text einer Zahlung („1. Kartenzahlung", „3. Barzahlung") --
+ * in der Aufschluesselung und ueber ihrem Kartenblock dieselbe Nummer, in
+ * Zahlungsreihenfolge ab 1.
+ */
+function zahlungNummerText(zahlung, index) {
+    return `${index + 1}. ${zahlungsartText(zahlung.method)}`;
+}
+/** „davon Trinkgeld" eingerueckt unter einer Zahlung, die Trinkgeld traegt. */
+function zahlungTrinkgeldZeilen(zahlung) {
+    if (typeof zahlung.tipCents !== 'number' || zahlung.tipCents <= 0)
+        return [];
+    return [paarZeile('  davon Trinkgeld', `${formatCents(zahlung.tipCents)} €`, 8, 4)];
+}
+/**
+ * Gegeben/Rueckgeld unter einer Barzahlung mit `tenderedCents`. Fehlt
+ * `changeCents` (der Server rechnet es sonst selbst), ergibt es sich aus
+ * gegeben minus Betrag.
+ */
+function barZeilen(zahlung) {
+    if (!BAR_ZAHLARTEN.includes(zahlartSchluessel(zahlung.method)) || typeof zahlung.tenderedCents !== 'number')
+        return [];
+    const rueckgeld = typeof zahlung.changeCents === 'number' ? zahlung.changeCents : zahlung.tenderedCents - zahlung.amountCents;
+    return [
+        paarZeile('  Gegeben:', `${formatCents(zahlung.tenderedCents)} €`, 8, 4),
+        paarZeile('  Rückgeld:', `${formatCents(rueckgeld)} €`, 8, 4),
+    ];
+}
+/**
+ * Die Zahlungszeilen unter „Gesamt:".
+ *
+ * - Ohne Zahlungsliste: „Zahlungsart: <Label>" aus `paymentMethod`, wie immer.
+ * - Genau eine Zahlung: dieselbe Zeile, Label aus der Zahlung.
+ * - Mehrere Zahlungen (auch zwei Karten, die `paymentMethod: creditCard`
+ *   ergeben -- entschieden wird an der Laenge, nie an `mixed`): „Zahlungsarten:"
+ *   und je Zahlung eine nummerierte Zeile mit Betrag, ohne Anbieter (der
+ *   steht im Kartenblock mit derselben Nummer). Breite 8:4 -- auf 58 mm
+ *   bleiben der Betragsspalte elf Zeichen, genug fuer „-9999,99 €".
+ *
+ * Unter jeder Zahlung in dieser Reihenfolge: „davon Trinkgeld" (bei
+ * `tipCents`), dann bei einer Barzahlung mit gegebenem Betrag „Gegeben:" und
+ * „Rückgeld:" -- alles, was zu einer Zahlung gehoert, zwei Zeichen eingerueckt,
+ * die Zahlung selbst buendig.
+ */
+function zahlungsZeilen(receipt) {
+    const zahlungen = receipt.payments;
+    if (zahlungen == null || zahlungen.length === 0) {
+        return [paarZeile('Zahlungsart:', zahlungsartText(receipt.paymentMethod))];
+    }
+    if (zahlungen.length === 1) {
+        const zahlung = zahlungen[0];
+        return [paarZeile('Zahlungsart:', zahlungsartText(zahlung.method)), ...zahlungTrinkgeldZeilen(zahlung), ...barZeilen(zahlung)];
+    }
+    const zeilen = [textZeile('Zahlungsarten:')];
+    zahlungen.forEach((zahlung, i) => {
+        zeilen.push(paarZeile(zahlungNummerText(zahlung, i), `${formatCents(zahlung.amountCents)} €`, 8, 4));
+        zeilen.push(...zahlungTrinkgeldZeilen(zahlung));
+        zeilen.push(...barZeilen(zahlung));
+    });
+    return zeilen;
+}
 // -------------------------------------------------------- Kleinunternehmer
 /**
  * Hinweis auf die Steuerbefreiung, den ein Kleinunternehmerbeleg tragen muss —
@@ -910,7 +1012,7 @@ function buildReceiptLayout(receipt, company, options = {}) {
         lines.push({ kind: 'rule', char: '-' });
     }
     lines.push(paarZeile('Gesamt:', `${formatCents(summeCents)} €`));
-    lines.push(paarZeile('Zahlungsart:', zahlungsartText(receipt.paymentMethod)));
+    lines.push(...zahlungsZeilen(receipt));
     lines.push({ kind: 'space', lines: 1 });
     // --- Rechtshinweise und Ausfallhinweis
     const hinweise = company.isSmallBusiness

package/dist/esm/client/api.d.ts

@@ -3,7 +3,7 @@ import { type CreateStripeLinkOptions, type StripeCaptureResult } from '../payme
 import { type HobexPayOptions, type HobexRefundOptions } from '../payments/hobex.js';
 import { type TransportOptions } from './transport.js';
 import { type CashboxStatus, type SignatureStatus } from './status.js';
-import { type SendReceiptEmailOptions, type SendReceiptEmailResult, type ListMyReceiptsOptions, type ReceiptList, type ReceiptWithCompany, type SellReceiptOptions, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions } from './receipts.js';
+import { type SendReceiptEmailOptions, type SendReceiptEmailResult, type ListMyReceiptsOptions, type ReceiptList, type ReceiptWithCompany, type SellReceiptOptions, type SellReceiptWithPaymentsOptions, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions } from './receipts.js';
 /**
  * Schlichte Factory ueber den Endpunkt-Funktionen: bindet einen Transport
  * einmal und liefert die Aufrufe ohne den wiederkehrenden ersten Parameter.
@@ -30,9 +30,9 @@ import { type SendReceiptEmailOptions, type SendReceiptEmailResult, type ListMyR
  */
 export interface KasseneckApi {
     /** Normalbeleg (Verkauf). */
-    sellReceipt(options: SellReceiptOptions): Promise<Receipt>;
+    sellReceipt(options: SellReceiptOptions | SellReceiptWithPaymentsOptions): Promise<Receipt>;
     /** Normalbeleg samt Firmen-/Druckdaten fuer den Belegdruck. */
-    sellReceiptWithCompany(options: SellReceiptOptions): Promise<ReceiptWithCompany>;
+    sellReceiptWithCompany(options: SellReceiptOptions | SellReceiptWithPaymentsOptions): Promise<ReceiptWithCompany>;
     /** Storno eines bestehenden Belegs — voll oder in Teilen, ueber den Storno-Endpunkt. */
     cancelReceipt(options: CancelReceiptOptions): Promise<CancelReceiptResult>;
     /** Storno aus frei uebergebenen Positionen. */

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

@@ -2,7 +2,7 @@ export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type
 export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, createTransport, createBinaryTransport, } from './transport.js';
 export { AUFRUFE, type Aufruf, } from './aufrufe.js';
 export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, } from './errors.js';
-export { type ReceiptCommonOptions, type SellReceiptOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, type CancelReceiptResult, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, } from './receipts.js';
+export { type ReceiptCommonOptions, type SellReceiptOptions, type SellReceiptWithPaymentsOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, type CancelReceiptResult, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, } from './receipts.js';
 export { listMyCashregisters } from './cashregisters.js';
 export { downloadDailyReport, downloadMonthlyReport } from './reports.js';
 export { type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, } from './status.js';

package/dist/esm/client/receipts.d.ts

@@ -1,5 +1,5 @@
 import { ReceiptType, type ReceiptTypeKey, KeckPaymentMethod, type KeckPaymentMethodKey, CreditCardProvider } from '../enums/index.js';
-import { type Receipt, type ReceiptCompany, type ReceiptItem, type Voucher, type ReceiptSummary, type ReportMonth, type CancellationItem, type CancellationOf, type CancellationReason } from '../models/index.js';
+import { type Receipt, type ReceiptCompany, type ReceiptItem, type Voucher, type ReceiptSummary, type ReportMonth, type CancellationItem, type CancellationOf, type CancellationReason, type ReceiptPaymentInput } from '../models/index.js';
 import type { InternerTransport } from './aufrufe.js';
 import type { Pruefangaben, ReceiptLayout } from '../receipt/layout.js';
 import type { LogoStufe } from '../receipt/blatt.js';
@@ -90,11 +90,32 @@ export interface CreateReceiptOptions extends ReceiptCommonOptions {
      * ausdruecklich uebergebene `paymentMethod` sticht.
      */
     paymentMethodFromServer?: string;
+    /**
+     * Mehrere Zahlungen je Beleg (siehe [ReceiptPaymentInput]). Schliesst
+     * `paymentMethod`, `paymentMethodFromServer` und die Kartenfelder aus —
+     * die Kartenangaben gehoeren dann in die einzelne Zahlung (Backend:
+     * `PAYMENTS_CONFLICT`). Nur bei `standard` und `training`.
+     */
+    payments?: ReceiptPaymentInput[];
     items?: ReceiptItem[];
     vouchers?: Voucher[];
 }
+/** Verkauf mit einer Zahlungsart (`paymentMethod`, Kartenfelder aus [ReceiptCommonOptions]). */
 export interface SellReceiptOptions extends ReceiptCommonOptions {
     paymentMethod: KeckPaymentMethod | KeckPaymentMethodKey;
+    payments?: undefined;
+    items?: ReceiptItem[];
+    vouchers?: Voucher[];
+}
+/**
+ * Verkauf mit mehreren Zahlungen (`payments`, siehe [ReceiptPaymentInput]).
+ * Ohne `paymentMethod` und ohne die Kartenfelder aus [ReceiptCommonOptions] —
+ * die Kartenangaben stehen in der einzelnen Zahlung (Backend:
+ * `PAYMENTS_CONFLICT`, zur Laufzeit ebenso geprueft).
+ */
+export interface SellReceiptWithPaymentsOptions extends ReceiptCommonOptions {
+    payments: ReceiptPaymentInput[];
+    paymentMethod?: undefined;
     items?: ReceiptItem[];
     vouchers?: Voucher[];
 }
@@ -126,6 +147,14 @@ export type CancelReceiptOptions = {
     creditCardProvider?: CreditCardProvider;
     cardPaymentId?: string;
     cardPaymentData?: Record<string, unknown>;
+    /**
+     * Rueckzahlung je Zahlung (Betraege negativ, `refundOf` = `id` der
+     * Originalzahlung). Schliesst `paymentMethod` und die Kartenfelder aus
+     * (Backend: `PAYMENTS_CONFLICT`). Ohne Angabe spiegelt der Server die
+     * Restbetraege jeder Originalzahlung; ein Teilstorno eines Belegs mit
+     * mehreren Zahlungen braucht sie (`STORNO_PAYMENTS_REQUIRED`).
+     */
+    payments?: ReceiptPaymentInput[];
 } & ({
     receipt: Receipt;
     cashregisterId?: string;
@@ -183,12 +212,12 @@ export interface ReceiptWithCompany {
  */
 export declare function createReceipt(rufen: InternerTransport, options: CreateReceiptOptions): Promise<Receipt>;
 /** Normalbeleg (Verkauf) nach RKSV. */
-export declare function sellReceipt(rufen: InternerTransport, options: SellReceiptOptions): Promise<Receipt>;
+export declare function sellReceipt(rufen: InternerTransport, options: SellReceiptOptions | SellReceiptWithPaymentsOptions): Promise<Receipt>;
 /**
  * Normalbeleg wie [sellReceipt], liefert zusaetzlich die Firmen-/Druckdaten
  * aus derselben Antwort — alles, was ein Belegdruck braucht, in einem Aufruf.
  */
-export declare function sellReceiptWithCompany(rufen: InternerTransport, options: SellReceiptOptions): Promise<ReceiptWithCompany>;
+export declare function sellReceiptWithCompany(rufen: InternerTransport, options: SellReceiptOptions | SellReceiptWithPaymentsOptions): Promise<ReceiptWithCompany>;
 /**
  * Storno-Beleg zu einem bestehenden Beleg — voll oder in Teilen. Prueft die
  * Eingabe, bevor etwas hinausgeht; der Server haelt die Restmengen und die

package/dist/esm/client/receipts.js

@@ -50,6 +50,22 @@ function createReceiptParams(options) {
     if (items != null && items.length > 0) {
         params['items'] = alsNutzlast(items, toReceiptItemPayload);
     }
+    // `payments: null` gilt wie im Backend (zahlungs-eingang.js) als nicht angegeben.
+    if (options.payments != null) {
+        // Der alte Storno-Weg und der Null-/Startbeleg nehmen keine Zahlungsliste
+        // (Backend: PAYMENTS_NOT_ALLOWED); ein Storno mit mehreren Zahlungen
+        // laeuft ueber cancelReceipt.
+        if (typ.value === ReceiptType.cancellation.value) {
+            throw eingabefehler('payments am Storno gehen nur ueber cancelReceipt.');
+        }
+        if (typ.value !== ReceiptType.standard.value && typ.value !== ReceiptType.training.value) {
+            throw eingabefehler(`payments sind bei receiptType "${typ.value}" nicht erlaubt.`);
+        }
+        const konflikt = zahlungsKonflikt(options);
+        if (konflikt != null)
+            throw eingabefehler(konflikt);
+        params['payments'] = gepruefteZahlungen(options.payments, false, 'createReceipt');
+    }
     // Vom Aufrufer kommt sie geprueft, vom Server roh — siehe die beiden Felder
     // in [CreateReceiptOptions]. Die Typpruefung allein reicht dafuer nicht: ein
     // Verbraucher ohne Typen faellt durch dieses Netz, und ein Tippfehler in der
@@ -133,11 +149,15 @@ export async function cancelReceipt(rufen, options) {
     if (options.note !== undefined && options.note.length > NOTE_MAX) {
         throw new KasseneckValidationError('cancelReceipt', `Anmerkung ist zu lang (hoechstens ${NOTE_MAX} Zeichen)`, 'request');
     }
+    // `payments: null` gilt wie im Backend als nicht angegeben.
+    const zahlungen = options.payments != null ? gepruefteStornoZahlungen(options) : undefined;
     const params = { cashregisterId, originalReceiptId, reason: options.reason };
     if (options.items !== undefined)
         params.items = options.items.map((p) => ({ index: p.index, quantity: p.quantity }));
     if (options.note !== undefined && options.note !== '')
         params.note = options.note;
+    if (zahlungen !== undefined)
+        params.payments = zahlungen;
     if (options.paymentMethod != null)
         params.paymentMethod = gepruefteZahlungsart(options.paymentMethod);
     const karte = options.creditCardProvider != null || options.cardPaymentId != null || options.cardPaymentData != null;
@@ -491,15 +511,110 @@ function gepruefterTip(tip) {
     }
     return nutzlast;
 }
-/** Zahlungsart des Aufrufers pruefen — unbekannt wirft, bevor etwas rausgeht. */
+/**
+ * Zahlungsart des Aufrufers pruefen — unbekannt wirft, bevor etwas rausgeht.
+ * `mixed` wirft ebenfalls: den Wert vergibt nur der Server (Beleg mit
+ * mehreren Zahlarten); gesendet wird stattdessen die Zahlungsliste.
+ */
 function gepruefteZahlungsart(wert) {
-    if (typeof wert === 'object') {
-        return wert.value;
+    let zahlungsart;
+    if (typeof wert === 'object' && wert !== null) {
+        zahlungsart = wert.value;
+    }
+    else {
+        if (typeof wert !== 'string' || !Object.prototype.hasOwnProperty.call(KeckPaymentMethod, wert)) {
+            throw eingabefehler(`Zahlungsart: unbekannter Schluessel "${String(wert)}"`);
+        }
+        zahlungsart = KeckPaymentMethod[wert].value;
     }
-    if (!Object.prototype.hasOwnProperty.call(KeckPaymentMethod, wert)) {
-        throw eingabefehler(`Zahlungsart: unbekannter Schluessel "${wert}"`);
+    if (zahlungsart === KeckPaymentMethod.mixed.value) {
+        throw eingabefehler('Zahlungsart "mixed" vergibt nur der Server – mehrere Zahlarten gehen als payments hinaus.');
     }
-    return KeckPaymentMethod[wert].value;
+    return zahlungsart;
+}
+/** Hoechstzahl der Zahlungen je Beleg (Backend: MAX_ZAHLUNGEN). */
+const MAX_ZAHLUNGEN = 20;
+/**
+ * `payments` neben einer Einzel-Zahlungsart oder Kartenfeldern? Liefert den
+ * Grund (Backend: PAYMENTS_CONFLICT), sonst null. Nie still eines bevorzugen.
+ */
+function zahlungsKonflikt(options) {
+    for (const feld of ['paymentMethod', 'paymentMethodFromServer', 'creditCardProvider', 'cardPaymentId', 'cardPaymentData']) {
+        if (options[feld] != null) {
+            return `payments und ${feld} duerfen nicht gemeinsam gesendet werden – Kartenangaben gehoeren in die Zahlung.`;
+        }
+    }
+    return null;
+}
+/**
+ * Zahlungsliste pruefen und in Nutzlast-Form bringen — Formpruefung wie
+ * `pruefeZahlungen` im Backend, soweit sie ohne Beleg und Zahlbetrag geht
+ * (Summe, Anbieter-Pflicht und Trinkgeld prueft der Server). Wirft, bevor
+ * etwas hinausgeht.
+ */
+function gepruefteZahlungen(roh, storno, functionName) {
+    const fehler = (grund) => new KasseneckValidationError(functionName, grund, 'request');
+    if (!Array.isArray(roh))
+        throw fehler('payments muss eine Liste sein.');
+    if (roh.length > MAX_ZAHLUNGEN)
+        throw fehler(`payments: es sind hoechstens ${MAX_ZAHLUNGEN} Eintraege erlaubt.`);
+    return roh.map((eintrag, i) => {
+        const nr = i + 1;
+        if (eintrag == null || typeof eintrag !== 'object' || Array.isArray(eintrag)) {
+            throw fehler(`Zahlung ${nr}: kein gueltiges Objekt.`);
+        }
+        const z = eintrag;
+        const method = gepruefteZahlungsart(z['method']);
+        const betrag = z['amountCents'];
+        if (typeof betrag !== 'number' || !Number.isInteger(betrag) || (storno ? betrag >= 0 : betrag <= 0)) {
+            throw fehler(`Zahlung ${nr}: amountCents muss eine ganze Zahl ${storno ? 'kleiner' : 'groesser'} als 0 sein.`);
+        }
+        const aus = { method, amountCents: betrag };
+        if (z['tenderedCents'] !== undefined) {
+            const gegeben = z['tenderedCents'];
+            if (storno || typeof gegeben !== 'number' || !Number.isInteger(gegeben) || gegeben < betrag) {
+                throw fehler(`Zahlung ${nr}: tenderedCents muss eine ganze Zahl von mindestens amountCents sein (nur am Verkauf).`);
+            }
+            aus['tenderedCents'] = gegeben;
+        }
+        if (z['tipCents'] !== undefined) {
+            const trinkgeld = z['tipCents'];
+            if (typeof trinkgeld !== 'number' || !Number.isInteger(trinkgeld) || trinkgeld <= 0) {
+                throw fehler(`Zahlung ${nr}: tipCents muss eine ganze Zahl groesser als 0 sein.`);
+            }
+            aus['tipCents'] = trinkgeld;
+        }
+        if (z['provider'] !== undefined) {
+            aus['provider'] = kartenanbieter(String(z['provider']));
+        }
+        if (z['providerPaymentId'] !== undefined) {
+            if (typeof z['providerPaymentId'] !== 'string' || z['providerPaymentId'] === '') {
+                throw fehler(`Zahlung ${nr}: providerPaymentId muss ein nicht-leerer Text sein.`);
+            }
+            aus['providerPaymentId'] = z['providerPaymentId'];
+        }
+        if (z['providerData'] !== undefined) {
+            const daten = z['providerData'];
+            if (daten === null || typeof daten !== 'object' || Array.isArray(daten)) {
+                throw fehler(`Zahlung ${nr}: providerData muss ein Objekt sein.`);
+            }
+            aus['providerData'] = daten;
+        }
+        if (z['refundOf'] !== undefined) {
+            if (!storno || typeof z['refundOf'] !== 'string' || z['refundOf'] === '') {
+                throw fehler(`Zahlung ${nr}: refundOf gibt es nur am Storno, als id der Originalzahlung.`);
+            }
+            aus['refundOf'] = z['refundOf'];
+        }
+        return aus;
+    });
+}
+/** `payments` am Storno: Konflikt mit Zahlungsart/Kartenfeldern, dann Form. */
+function gepruefteStornoZahlungen(options) {
+    const konflikt = zahlungsKonflikt(options);
+    if (konflikt != null)
+        throw new KasseneckValidationError('cancelReceipt', konflikt, 'request');
+    return gepruefteZahlungen(options.payments, true, 'cancelReceipt');
 }
 /** Kartenanbieter pruefen — er stammt vom Aufrufer, nicht aus Serverdaten. */
 function kartenanbieter(wert) {

package/dist/esm/enums/keck-payment-method.d.ts

@@ -5,6 +5,11 @@
  * `label` ist das deutsche Anzeige-Label fuer die Zahlungsart-Zeile auf dem Beleg.
  * Muss 1:1 mit dem Backend-Mapping `paymentMethodToString` (functions/helper.js)
  * uebereinstimmen.
+ *
+ * `mixed` vergibt nur der Server: ein Beleg mit mehreren Zahlungen
+ * verschiedener Zahlart (`payments`) traegt ihn als Einzelfeld
+ * `paymentMethod`. Lesen ist erlaubt, Senden nicht — wer mehrere Zahlarten
+ * kassiert, schickt die Zahlungsliste, nie `mixed`.
  */
 export declare const KeckPaymentMethod: {
     readonly cash: {
@@ -52,6 +57,11 @@ export declare const KeckPaymentMethod: {
         readonly needsCreditCard: true;
         readonly label: "Bolt Card";
     };
+    readonly mixed: {
+        readonly value: "mixed";
+        readonly needsCreditCard: false;
+        readonly label: "Mehrere Zahlungsarten";
+    };
 };
 export type KeckPaymentMethodKey = keyof typeof KeckPaymentMethod;
 export type KeckPaymentMethod = (typeof KeckPaymentMethod)[KeckPaymentMethodKey];

package/dist/esm/enums/keck-payment-method.js

@@ -6,6 +6,11 @@ import { defineEnum } from './define-enum.js';
  * `label` ist das deutsche Anzeige-Label fuer die Zahlungsart-Zeile auf dem Beleg.
  * Muss 1:1 mit dem Backend-Mapping `paymentMethodToString` (functions/helper.js)
  * uebereinstimmen.
+ *
+ * `mixed` vergibt nur der Server: ein Beleg mit mehreren Zahlungen
+ * verschiedener Zahlart (`payments`) traegt ihn als Einzelfeld
+ * `paymentMethod`. Lesen ist erlaubt, Senden nicht — wer mehrere Zahlarten
+ * kassiert, schickt die Zahlungsliste, nie `mixed`.
  */
 export const KeckPaymentMethod = defineEnum({
     cash: { value: 'cash', needsCreditCard: false, label: 'Barzahlung' },
@@ -17,4 +22,5 @@ export const KeckPaymentMethod = defineEnum({
     boltApp: { value: 'boltApp', needsCreditCard: false, label: 'Bolt App' },
     boltCash: { value: 'boltCash', needsCreditCard: false, label: 'Bolt Cash' },
     boltCard: { value: 'boltCard', needsCreditCard: true, label: 'Bolt Card' },
+    mixed: { value: 'mixed', needsCreditCard: false, label: 'Mehrere Zahlungsarten' },
 });

package/dist/esm/index.d.ts

@@ -1,5 +1,5 @@
 export { ReceiptType, type ReceiptTypeKey, VatRate, type VatRateKey, KeckPaymentMethod, type KeckPaymentMethodKey, CreditCardProvider, type CreditCardProviderKey, VoucherType, type VoucherTypeKey, VoucherAction, type VoucherActionKey, StripeLinkMode, type StripeLinkModeKey, } from './enums/index.js';
-export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, type ReceiptEmailErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, remainingQuantities, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, istZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
-export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, AUFRUFE, type Aufruf, createTransport, createBinaryTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, type ReceiptCommonOptions, type SellReceiptOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, listMyCashregisters, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, type KasseneckApi, createKasseneckApi, } from './client/index.js';
+export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, type ReceiptEmailErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, remainingQuantities, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, istZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
+export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, AUFRUFE, type Aufruf, createTransport, createBinaryTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, type ReceiptCommonOptions, type SellReceiptOptions, type SellReceiptWithPaymentsOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, listMyCashregisters, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, type KasseneckApi, createKasseneckApi, } from './client/index.js';
 export { parseServerTimeStamp, toViennaWallClock, type ViennaWallClock } from './vienna-time.js';
 export { type KasseSettingsBetrieb, type KasseSettingsGeraet, type KasseSettings, type ArticleGroup, type KasseArtikel, KASSE_BETRIEB_STANDARD, KASSE_GERAET_STANDARD, mergeKasseSettings, fromArticleGroupPayload, fromKasseArtikelPayload, listMyArticleGroups, listMyArticles, getKasseSettings, setMyKasseSettings, setMyRegisterDeviceSettings, verteileRabatt, cancelScopeOf, receiptsScopeOf, } from './kasse/index.js';

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 export { ReceiptType, VatRate, KeckPaymentMethod, CreditCardProvider, VoucherType, VoucherAction, StripeLinkMode, } from './enums/index.js';
-export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, toVoucherPayload, fromVoucherPayload, voucherIsValid, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, remainingQuantities, fromReceiptCompanyPayload, receiptCompanyTaxInfo, fromCashregisterPayload, fromReceiptSummaryPayload, ZERO_KINDS, istZeroKind, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
+export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, toVoucherPayload, fromVoucherPayload, voucherIsValid, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, fromReceiptPaymentPayload, toReceiptPaymentPayload, PAYMENT_ERROR_CODES, isPaymentErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, remainingQuantities, fromReceiptCompanyPayload, receiptCompanyTaxInfo, fromCashregisterPayload, fromReceiptSummaryPayload, ZERO_KINDS, istZeroKind, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
 export { apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, AUFRUFE, createTransport, createBinaryTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, listMyCashregisters, checkVoucherCombinationError, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, getCashboxStatus, getSignatureStatus, createKasseneckApi, } from './client/index.js';
 export { parseServerTimeStamp, toViennaWallClock } from './vienna-time.js';
 export { KASSE_BETRIEB_STANDARD, KASSE_GERAET_STANDARD, mergeKasseSettings, fromArticleGroupPayload, fromKasseArtikelPayload, listMyArticleGroups, listMyArticles, getKasseSettings, setMyKasseSettings, setMyRegisterDeviceSettings, verteileRabatt, cancelScopeOf, receiptsScopeOf, } from './kasse/index.js';

package/dist/esm/models/cancellation.d.ts

@@ -27,8 +27,18 @@ export declare function isCancellationReason(value: unknown): value is Cancellat
  *
  * Nur Auth-/Parameterfehler (Sitzung abgelaufen, Pflichtfeld fehlt) kommen
  * ohne Code; dort bleibt `code` undefined.
+ *
+ * Die vier `STORNO_…`-Codes am Ende gehoeren zur Rueckzahlung je Zahlung
+ * (mehrere Zahlungen je Beleg); Formfehler an `payments` selbst melden die
+ * Codes aus [PAYMENT_ERROR_CODES].
+ *
+ * Die Werte hier sind die von `/v1` und intern. Unter `/v3` heissen die
+ * Storno-Codes nach dem /v3-Vokabular anders (`already_cancelled`,
+ * `cancellation_payments_required`, functions/gemeinsam/api-vokabular-v3.js);
+ * diese Namen kommen mit der Umstellung des Pakets auf `/v3`.
+ * [isCancellationErrorCode] prueft darum exakt.
  */
-export declare const CANCELLATION_ERROR_CODES: readonly ["beleg_nicht_gefunden", "belegart_nicht_stornierbar", "trainingsbeleg", "bereits_storniert", "position_ungueltig", "menge_ueber_rest", "grund_unbekannt", "anmerkung_zu_lang", "items_ungueltig", "kasse_nicht_zugewiesen", "keine_berechtigung", "nur_eigene_belege", "kasse_unvollstaendig", "storno_fehlgeschlagen"];
+export declare const CANCELLATION_ERROR_CODES: readonly ["beleg_nicht_gefunden", "belegart_nicht_stornierbar", "trainingsbeleg", "bereits_storniert", "position_ungueltig", "menge_ueber_rest", "grund_unbekannt", "anmerkung_zu_lang", "items_ungueltig", "kasse_nicht_zugewiesen", "keine_berechtigung", "nur_eigene_belege", "kasse_unvollstaendig", "storno_fehlgeschlagen", "STORNO_PAYMENTS_REQUIRED", "STORNO_REFUND_EXCEEDS_PAYMENT", "STORNO_REFUND_REFERENCE_REQUIRED", "STORNO_REFUND_REFERENCE_UNKNOWN"];
 export type CancellationErrorCode = (typeof CANCELLATION_ERROR_CODES)[number];
 export declare function isCancellationErrorCode(value: unknown): value is CancellationErrorCode;
 /** Bezug eines Storno-Belegs auf sein Original. */

package/dist/esm/models/cancellation.js

@@ -27,6 +27,16 @@ export function isCancellationReason(value) {
  *
  * Nur Auth-/Parameterfehler (Sitzung abgelaufen, Pflichtfeld fehlt) kommen
  * ohne Code; dort bleibt `code` undefined.
+ *
+ * Die vier `STORNO_…`-Codes am Ende gehoeren zur Rueckzahlung je Zahlung
+ * (mehrere Zahlungen je Beleg); Formfehler an `payments` selbst melden die
+ * Codes aus [PAYMENT_ERROR_CODES].
+ *
+ * Die Werte hier sind die von `/v1` und intern. Unter `/v3` heissen die
+ * Storno-Codes nach dem /v3-Vokabular anders (`already_cancelled`,
+ * `cancellation_payments_required`, functions/gemeinsam/api-vokabular-v3.js);
+ * diese Namen kommen mit der Umstellung des Pakets auf `/v3`.
+ * [isCancellationErrorCode] prueft darum exakt.
  */
 export const CANCELLATION_ERROR_CODES = [
     'beleg_nicht_gefunden', // Original fehlt oder gehoert nicht zu dieser Kasse
@@ -43,6 +53,11 @@ export const CANCELLATION_ERROR_CODES = [
     'nur_eigene_belege', // Recht "eigene", fremder Beleg
     'kasse_unvollstaendig', // api_key/token fehlen am Konto bzw. an der Kasse
     'storno_fehlgeschlagen', // der Storno-Beleg selbst wurde abgelehnt (z. B. Signatur)
+    // Mehrere Zahlungen je Beleg (Rueckzahlung je Zahlung):
+    'STORNO_PAYMENTS_REQUIRED', // Teilstorno eines Belegs mit mehreren Zahlungen ohne payments
+    'STORNO_REFUND_EXCEEDS_PAYMENT', // Rueckzahlungen auf eine Zahlung uebersteigen deren Rest
+    'STORNO_REFUND_REFERENCE_REQUIRED', // Karten-Rueckzahlung ohne refundOf einer Kartenzahlung
+    'STORNO_REFUND_REFERENCE_UNKNOWN', // refundOf nennt keine Zahlung des Originals
 ];
 export function isCancellationErrorCode(value) {
     return typeof value === 'string' && CANCELLATION_ERROR_CODES.includes(value);

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

@@ -2,6 +2,8 @@ export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead,
 export { type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid } from './voucher.js';
 export { type Receipt, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, } from './receipt.js';
 export { type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, remainingQuantities, } from './cancellation.js';
+export { type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';
+export { type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode } from './payment-errors.js';
 export { type ReceiptEmailErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, } from './receipt-email.js';
 export { type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, } from './receipt-company.js';
 export { type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, fromCashregisterPayload, } from './cashregister.js';

package/dist/esm/models/index.js

@@ -2,6 +2,8 @@ export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, re
 export { toVoucherPayload, fromVoucherPayload, voucherIsValid } from './voucher.js';
 export { toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, } from './receipt.js';
 export { CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, remainingQuantities, } from './cancellation.js';
+export { fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';
+export { PAYMENT_ERROR_CODES, isPaymentErrorCode } from './payment-errors.js';
 export { RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, } from './receipt-email.js';
 export { fromReceiptCompanyPayload, receiptCompanyTaxInfo, } from './receipt-company.js';
 export { fromCashregisterPayload, } from './cashregister.js';

package/dist/esm/models/payment-errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Mehrere Zahlungen je Beleg — Fehlercode-Katalog, Zwilling von
+ * `functions/gemeinsam/zahlungen-core.js` ZAHLUNGS_FEHLERCODES (gleiche
+ * Codes, gleiche Reihenfolge).
+ *
+ * `createReceipt` und `cancelReceipt` legen sie bei jedem Fehler rund um
+ * `payments` (und bei den Aufrufer-Vorbedingungen wie `PAYMENTS_CONFLICT`)
+ * als `code` neben die Meldung; das Paket reicht sie als
+ * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text** — die
+ * deutsche Meldung darf sich aendern, der Code nicht.
+ *
+ * Schreibweise: auf `/v1`, `/v2` und intern kommen die Codes gross
+ * (`PAYMENTS_SUM_MISMATCH`), unter `/v3` schreibt der Rand des Backends sie
+ * klein (`payments_sum_mismatch`, functions/gemeinsam/api-vokabular-v3.js:
+ * jeder dieser Codes 1:1 in Kleinschreibung, anders als die Storno-Codes).
+ * [isPaymentErrorCode] erkennt beide; wer selbst vergleicht, vergleicht
+ * `code.toUpperCase()`.
+ */
+export declare const PAYMENT_ERROR_CODES: readonly ["PAYMENTS_INVALID", "PAYMENT_METHOD_INVALID", "PAYMENT_AMOUNT_INVALID", "PAYMENT_TENDERED_INVALID", "PAYMENT_PROVIDER_INVALID", "PAYMENT_PROVIDER_NOT_ALLOWED", "PAYMENTS_SUM_MISMATCH", "PAYMENTS_DUE_NEGATIVE", "PAYMENTS_NOT_ALLOWED", "PAYMENTS_CONFLICT", "PAYMENTS_REQUIRED", "PAYMENT_METHOD_NOT_SUPPORTED", "TIP_PAYMENT_METHOD_INVALID", "TIP_PAYMENT_METHOD_REQUIRED", "TIP_EXCEEDS_PAYMENT", "PAYMENT_REFUND_NOT_ALLOWED", "PAYMENT_TIP_INVALID", "TIP_CONFLICT"];
+export type PaymentErrorCode = (typeof PAYMENT_ERROR_CODES)[number];
+/** Erkennt einen Code aus [PAYMENT_ERROR_CODES] — gross (`/v1`) wie klein (`/v3`). */
+export declare function isPaymentErrorCode(value: unknown): value is PaymentErrorCode | Lowercase<PaymentErrorCode>;

package/dist/esm/models/payment-errors.js

@@ -0,0 +1,42 @@
+/**
+ * Mehrere Zahlungen je Beleg — Fehlercode-Katalog, Zwilling von
+ * `functions/gemeinsam/zahlungen-core.js` ZAHLUNGS_FEHLERCODES (gleiche
+ * Codes, gleiche Reihenfolge).
+ *
+ * `createReceipt` und `cancelReceipt` legen sie bei jedem Fehler rund um
+ * `payments` (und bei den Aufrufer-Vorbedingungen wie `PAYMENTS_CONFLICT`)
+ * als `code` neben die Meldung; das Paket reicht sie als
+ * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text** — die
+ * deutsche Meldung darf sich aendern, der Code nicht.
+ *
+ * Schreibweise: auf `/v1`, `/v2` und intern kommen die Codes gross
+ * (`PAYMENTS_SUM_MISMATCH`), unter `/v3` schreibt der Rand des Backends sie
+ * klein (`payments_sum_mismatch`, functions/gemeinsam/api-vokabular-v3.js:
+ * jeder dieser Codes 1:1 in Kleinschreibung, anders als die Storno-Codes).
+ * [isPaymentErrorCode] erkennt beide; wer selbst vergleicht, vergleicht
+ * `code.toUpperCase()`.
+ */
+export const PAYMENT_ERROR_CODES = Object.freeze([
+    'PAYMENTS_INVALID', // payments ist keine Liste oder hat mehr als 20 Eintraege
+    'PAYMENT_METHOD_INVALID', // Zahlart unbekannt oder mixed
+    'PAYMENT_AMOUNT_INVALID', // amountCents keine Ganzzahl, 0 oder falsches Vorzeichen
+    'PAYMENT_TENDERED_INVALID', // tenderedCents an Nicht-Bar-Zahlung, zu klein oder doppelt
+    'PAYMENT_PROVIDER_INVALID', // Karte ohne/mit unbekanntem provider, providerPaymentId fehlt
+    'PAYMENT_PROVIDER_NOT_ALLOWED', // Anbieterfelder an einer Zahlung, die weder Karte noch online ist
+    'PAYMENTS_SUM_MISMATCH', // Summe != Zahlbetrag (Antwort nennt data.expectedCents)
+    'PAYMENTS_DUE_NEGATIVE', // Zahlbetrag < 0 (Wertgutschein groesser als der Beleg)
+    'PAYMENTS_NOT_ALLOWED', // Null-/Startbeleg mit Zahlungen, alter Storno-Weg
+    'PAYMENTS_CONFLICT', // payments zusammen mit paymentMethod oder Kartenfeldern
+    'PAYMENTS_REQUIRED', // /v3 ohne payments
+    'PAYMENT_METHOD_NOT_SUPPORTED', // paymentMethod/Kartenfelder unter /v3
+    'TIP_PAYMENT_METHOD_INVALID', // Trinkgeld-Zahlart kommt in payments nicht vor
+    'TIP_PAYMENT_METHOD_REQUIRED', // mehrere Zahlarten, tip.paymentMethod fehlt
+    'TIP_EXCEEDS_PAYMENT', // Trinkgeld uebersteigt die Zahlungen seiner Zahlart
+    'PAYMENT_REFUND_NOT_ALLOWED', // refundOf ausserhalb eines Stornos oder kein String
+    'PAYMENT_TIP_INVALID', // tipCents keine Ganzzahl, <= 0, > amountCents oder nicht am Verkauf
+    'TIP_CONFLICT', // tip und payments[].tipCents zugleich
+]);
+/** Erkennt einen Code aus [PAYMENT_ERROR_CODES] — gross (`/v1`) wie klein (`/v3`). */
+export function isPaymentErrorCode(value) {
+    return typeof value === 'string' && PAYMENT_ERROR_CODES.includes(value.toUpperCase());
+}