Refunds

Über

Das Plugin erweitert `@payloadcms/plugin-ecommerce` um die Verwaltung von vollständigen und teilweisen Rückerstattungen. Es legt eine `refunds`-Collection an, in der jede Rückerstattung als normales Dokument über `payload.create` gespeichert wird. Die Bestell-Collection wird um die Felder `refundedAmount` und `refundableAmount` ergänzt, die mit den Rückerstattungsdatensätzen synchron bleiben. Alle Beträge sind ganze Minoreinheiten (Cent), werden als Integer gespeichert und verglichen. Fraktionale Beträge werden abgelehnt statt gerundet. Das Plugin muss nach der Bestell-Collection registriert werden. Ist diese nicht vorhanden, gibt es die Konfiguration unverändert zurück und kann in jedem Projekt geladen werden. `refundedAmount` wird bei jedem Schreibvorgang aus den Rückerstattungsdatensätzen neu berechnet und nie inkrementiert, wodurch ein Abweichen vom Verlauf ausgeschlossen ist. Pro Rückerstattung lassen sich eine oder mehrere Bestellpositionen angeben. Die Anzahl der rückerstatteten Einheiten über alle Datensätze hinweg übersteigt nie die bestellten Einheiten. Bei ungültigen Beträgen (null, negativ, fraktional, über dem rückerstattbaren Restbetrag) oder bei Überschreitung der Zeilenlimits wird die Rückerstattung mit `RefundError` (HTTP 400) abgelehnt. Die Fehlercodes umfassen `InvalidAmount`, `InvalidLine`, `LineOverRefund`, `LinesExceedAmount`, `OrderNotFound`, `OverRefund`, `RefundImmutable` und `WrongCurrency`. Der `onRefund`-Hook läuft nach der Validierung und vor dem Schreiben des Datensatzes. Schlägt der Aufruf des Zahlungsanbieters fehl, bleibt kein Datensatz zurück. Die Rückgabe eines `reference`-Werts speichert die ID des Anbieters auf dem Datensatz. Der optionale Restock gibt rückerstattete Einheiten über Compare-and-Set-Schreibvorgänge mit Retries in das Produkt- oder Variantendokument zurück, das bei dem Verkauf ursprünglich belastet wurde. So werden konkurrierende Änderungen nicht überschrieben. `updateTransactionStatus` markiert die entsprechende Transaktion als `refunded`, sobald die gesamte Bestellung rückerstattet ist. `refundedStatus` steuert, ob der Bestellstatus selbst geschrieben wird: Ein leerer String belässt ihn unverändert, was bei Teilrückerstattungen sinnvoll ist. Das Paket enthält keine Admin-Komponenten und keine Runtime-Abhängigkeiten. Das gilt auch für einen Runtime-Import von `payload`, was Stabilität über minor Payload-Releases hinweg sichert. Da das offizielle Ecommerce-Plugin keinen zeilenbasierten Preis speichert, sind Zeilenlimits rein mengenbasiert. Rückerstattungsdatensätze sind append-only: Der `beforeChange`-Hook blockiert jede Operation außer `create`, wodurch der Audit-Trail nicht nachträglich bearbeitet werden kann.

Paketinformationen

Paketname

payload-refunds

Neueste Version

1.0.1

Entpackte Größe

52 kB

Lizenz

MIT

Wöchentliche Downloads

3

Zuletzt veröffentlicht

21. Aug. 2026