Zum Hauptinhalt springen
Ein Zahlungsplan hängt an genau einer offenen Rechnung und besteht aus einer geordneten Liste von Raten. Diese Seite erklärt die Felder, die du beim Anlegen setzt, und die Regeln dahinter.

​
Plan

FeldTypBeschreibung
idstringKennung des Plans (UUID).
invoiceIdstringDie Rechnung, die aufgeteilt wird.
statusstringLebenszyklus: active, completed, broken oder canceled.
totalAmountintegerSumme aller Raten in Cent. Entspricht bei der Anlage dem offenen Betrag der Rechnung.
currencyCodestringWährung, zum Beispiel EUR.
paymentMethodIdstring | nullZahlungsmethode für den Einzug. Standard ist die Zahlungsmethode der Rechnung, ersatzweise die Standard-Methode des Kunden.
createdAtstringZeitpunkt der Anlage (ISO 8601).
completedAtstring | nullZeitpunkt, an dem alle Raten bezahlt waren, sonst null.
brokenAtstring | nullZeitpunkt eines Planbruchs, sonst null.
canceledAtstring | nullZeitpunkt der Kündigung, sonst null.
brokenReasonstring | nullGrund des Planbruchs, sonst null.
installmentsarrayDie Raten, sortiert nach ihrer Position.

​
Status-Lebenszyklus

StatusBedeutung
activeLäuft. Das Mahnwesen für die Rechnung ruht, fällige Lastschrift-Raten werden eingezogen.
completedAbgeschlossen. Alle Raten sind bezahlt, die Rechnung ist beglichen.
brokenGebrochen. Eine Rate ist ausgefallen oder überfällig geblieben. Der Restbetrag ist sofort fällig, das Mahnwesen läuft wieder.
canceledGekündigt. Der Plan wurde manuell beendet, das Mahnwesen läuft wieder.
Solange der Plan active ist, wird die Rechnung im Mahnlauf übersprungen. In jedem anderen Status wird sie wieder wie üblich gemahnt. Ein gebrochener Plan lässt sich verlängern und kehrt damit nach active zurück.

​
Rate

Eine Rate (installment) ist ein Teilbetrag mit einem Fälligkeitsdatum.
FeldTypBeschreibung
idstringKennung der Rate (UUID).
positionintegerRang innerhalb des Plans, beginnend bei 1.
dueAtstringFälligkeitsdatum im Format Y-m-d.
amountintegerBetrag der Rate in Cent.
statusstringopen, collecting, paid oder failed.
paidAtstring | nullZeitpunkt, an dem die Rate vollständig gedeckt war, sonst null.

​
Raten-Status

StatusBedeutung
openOffen. Noch nicht eingezogen und noch nicht gedeckt.
collectingIm Einzug. Für diese Rate wurde eine Lastschrift ausgelöst und läuft.
paidBezahlt. Der Betrag ist eingegangen.
failedFehlgeschlagen. Der Einzug ist gescheitert, der Plan bricht.

​
Beträge und Rundung

Alle Beträge sind ganze Zahlen in der kleinsten Währungseinheit (Cent). 1190 bedeutet 11,90 Euro. Die Summe der Raten muss dem offenen Betrag der Rechnung zum Zeitpunkt der Anlage entsprechen. Stimmt sie nicht, antwortet die API mit 422 und dem Schlüssel PAYMENT_PLAN__SUM_MISMATCH. Im Split-Modus teilt Fynn den offenen Betrag gleichmäßig auf. Geht die Division nicht glatt auf, landet der Rundungsrest auf der letzten Rate. Beispiel: 100,00 Euro in drei Raten ergibt 33,33 / 33,33 / 33,34.

​
Anlegen: manuell oder splitten

Beim Anlegen wählst du genau einen der beiden Wege. Sendest du beide oder keinen, antwortet die API mit 422. 
{
  "invoiceId": "10000000-0000-0000-0003-000000000001",
  "installments": [
    { "dueAt": "2026-08-05", "amount": 595 },
    { "dueAt": "2026-09-05", "amount": 595 }
  ]
}
  • Manuell (installments): Du gibst jede Rate mit Datum und Betrag vor. Die Termine müssen aufsteigend und in der Zukunft liegen, jeder Betrag positiv sein.
  • Gleichmäßig (split): Du gibst count (2 bis 36), interval (Abstand als {n}{D|W|M|Y}, Standard 1M) und firstDueAt an. Fynn berechnet Beträge und Termine.
Eine Rechnung kann nur einen aktiven Plan haben. Ein neuer Plan ist erst möglich, wenn ein bestehender abgeschlossen, gebrochen oder gekündigt ist. Um einem Kunden mehr Zeit zu geben, verlängere den bestehenden Plan, statt einen neuen anzulegen.

​
Einzug und Erinnerung

Die Zahlungsmethode des Plans bestimmt, wie eine Rate beglichen wird.
  • Lastschrift (SEPA): Fynn löst den Einzug automatisch sieben Tage vor Fälligkeit aus. Die Rate wechselt dabei auf collecting.
  • Überweisung: Der Kunde überweist selbst. Fynn ordnet den Zahlungseingang der offenen Rechnung zu.
In beiden Fällen erhält der Kunde sieben Tage vor Fälligkeit eine E-Mail, entweder als Ankündigung des Einzugs oder als Zahlungsaufforderung.

​
Voraussetzungen an die Rechnung

Ein Plan lässt sich nur für eine Rechnung anlegen, die
  • finalisiert und offen ist (nicht Entwurf, bezahlt, storniert oder erstattet), und
  • noch keinen aktiven Plan hat.
Ist die Rechnung nicht geeignet, antwortet die API mit 422 und dem Schlüssel PAYMENT_PLAN__INVOICE_NOT_ELIGIBLE.