Kernkonzepte

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

Feld	Typ	Beschreibung
`id`	string	Kennung des Plans (UUID).
`invoiceId`	string	Die Rechnung, die aufgeteilt wird.
`status`	string	Lebenszyklus: `active`, `completed`, `broken` oder `canceled`.
`totalAmount`	integer	Summe aller Raten in Cent. Entspricht bei der Anlage dem offenen Betrag der Rechnung.
`currencyCode`	string	Währung, zum Beispiel `EUR`.
`paymentMethodId`	string \| null	Zahlungsmethode für den Einzug. Standard ist die Zahlungsmethode der Rechnung, ersatzweise die Standard-Methode des Kunden.
`createdAt`	string	Zeitpunkt der Anlage (ISO 8601).
`completedAt`	string \| null	Zeitpunkt, an dem alle Raten bezahlt waren, sonst `null`.
`brokenAt`	string \| null	Zeitpunkt eines Planbruchs, sonst `null`.
`canceledAt`	string \| null	Zeitpunkt der Kündigung, sonst `null`.
`brokenReason`	string \| null	Grund des Planbruchs, sonst `null`.
`installments`	array	Die Raten, sortiert nach ihrer Position.

Status-Lebenszyklus

Status	Bedeutung
`active`	Läuft. Das Mahnwesen für die Rechnung ruht, fällige Lastschrift-Raten werden eingezogen.
`completed`	Abgeschlossen. Alle Raten sind bezahlt, die Rechnung ist beglichen.
`broken`	Gebrochen. Eine Rate ist ausgefallen oder überfällig geblieben. Der Restbetrag ist sofort fällig, das Mahnwesen läuft wieder.
`canceled`	Gekü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.

Feld	Typ	Beschreibung
`id`	string	Kennung der Rate (UUID).
`position`	integer	Rang innerhalb des Plans, beginnend bei 1.
`dueAt`	string	Fälligkeitsdatum im Format `Y-m-d`.
`amount`	integer	Betrag der Rate in Cent.
`status`	string	`open`, `collecting`, `paid` oder `failed`.
`paidAt`	string \| null	Zeitpunkt, an dem die Rate vollständig gedeckt war, sonst `null`.

Raten-Status

Status	Bedeutung
`open`	Offen. Noch nicht eingezogen und noch nicht gedeckt.
`collecting`	Im Einzug. Für diese Rate wurde eine Lastschrift ausgelöst und läuft.
`paid`	Bezahlt. Der Betrag ist eingegangen.
`failed`	Fehlgeschlagen. 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 }
  ]
}

{
  "invoiceId": "10000000-0000-0000-0003-000000000001",
  "split": { "count": 3, "interval": "1M", "firstDueAt": "2026-08-05" }
}

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.

Einführung

Grundlagen

Pläne

Angebote

Provisionen

Zahlungspläne

Plan

Status-Lebenszyklus

Rate

Raten-Status

Beträge und Rundung

Anlegen: manuell oder splitten

Einzug und Erinnerung

Voraussetzungen an die Rechnung

​Plan

​Status-Lebenszyklus

​Rate

​Raten-Status

​Beträge und Rundung

​Anlegen: manuell oder splitten

​Einzug und Erinnerung

​Voraussetzungen an die Rechnung

Plan

Status-Lebenszyklus

Rate

Raten-Status

Beträge und Rundung

Anlegen: manuell oder splitten

Einzug und Erinnerung

Voraussetzungen an die Rechnung