Konzepte: Zahlungsstatus

Zahlungstransaktionen sind ein zentraler Bestandteil der kaufmännischen Abwicklung in der tebio Plattform. Jeder Zahlungsvorgang (egal ob per Kreditkarte, PayPal oder SEPA) durchläuft ein definiertes Statusmodell.

Da Zahlungen häufig oft über Weiterleitungen (Redirects zu Zahlungsanbietern) und asynchrone Bestätigungen (wie 3D-Secure) laufen, ist das Verständnis dieses Modells wichtig für Integration, Support und Buchhaltung.

1. Haupttransaktionen verstehen

Sobald eine neue Zahlung (startPayment) in der Plattform ausgelöst wird, befindet sie sich in einem Übergangszustand. Das folgende Diagramm zeigt die möglichen Statusübergänge der State Machine:

stateDiagram-v2
    [*] --> NEW
    NEW --> PENDING
    
    note left of PENDING : Mögliche Aktionen\n- Finalize
    
    PENDING --> PAYM_RES
    PENDING --> CLOSED_FAILED
    PENDING --> CLOSED_OK
    
    note right of PAYM_RES : Mögliche Aktionen\n- Capture\n- Cancel\n- Finalize
    
    PAYM_RES --> CLOSED_OK
    
    note left of CLOSED_FAILED : Mögliche Aktionen\n- Finalize (kein Effekt)
    
    note right of CLOSED_OK : Mögliche Aktionen\n- Refund\n- Finalize (kein Effekt)

Statuswerte im Detail:

PENDING (Ausstehend): Der Startpunkt. Die Zahlung wartet auf die Authentifizierung oder Autorisierung durch den Kunden (z. B. den Login bei PayPal). Dieser Status bleibt bestehen, bis die maximale Wartezeit (Timeout) abgelaufen ist oder ein Ergebnis vorliegt.
PAYM_RES (Reserviert): Die Zahlung wurde erfolgreich beim Kunden reserviert, aber das Geld wurde noch nicht eingezogen. (Tritt nur bei Zahlungen vom Typ “RESERVE” auf, siehe unten).
CLOSED_OK (Erfolgreich): Die Zahlung ist abgeschlossen. Entweder wurde das Geld sofort eingezogen, oder eine vorangegangene Reservierung (PAYM_RES) hat ihr logisches Ende erreicht.
CLOSED_FAILED (Fehlgeschlagen): Die Zahlung wurde abgelehnt (z. B. Limit erreicht, falsche IBAN) oder der Kunde hat den Vorgang beim Zahlungsanbieter abgebrochen.

2. Reservierung und sofortiger Einzug (Capture Types)

Das Statusmodell wird maßgeblich dadurch beeinflusst, wie die Zahlung initialisiert wurde. Die tebio Plattform unterscheidet zwei Capture Types:

Sofortiger Einzug (`IMMEDIATE`)

Das ist der Standardfall für digitale Subscriptions. Der Betrag wird sofort autorisiert und eingezogen.

Ablauf: Die Transaktion wechselt bei Erfolg von PENDING direkt auf CLOSED_OK.

Reservierung (`RESERVE`)

Wird häufig beim Versand physischer Waren genutzt: Sie autorisieren den Betrag beim Kauf, buchen ihn aber erst ab, wenn die Ware das Lager verlässt.

Ablauf: Die Transaktion wechselt bei Erfolg von PENDING zunächst auf PAYM_RES.
Um das Geld wirklich zu erhalten, muss später ein explizites Capture (Einzug) ausgelöst werden.
Wichtig: Eine Reservierungstransaktion wechselt später immer auf CLOSED_OK, unabhängig davon, ob das Geld eingezogen (Capture) oder die Reservierung storniert (Cancel) wurde. Der Status der Haupttransaktion spiegelt den Erfolg der Reservierung wider. Um zu sehen, was mit dem Geld passiert ist, müssen Sie die Untertransaktionen betrachten.

3. Untertransaktionen

Jede Aktion, die auf einer bestehenden Haupttransaktion aufbaut, erzeugt in der tebio Plattform eine separate Untertransaktion. Da es für eine einzige Reservierung mehrere Teileinzüge oder Teilstornierungen geben kann, haben Untertransaktionen ein eigenes, vereinfachtes Statusmodell.

Typische Untertransaktionen sind:

CAPTURE (Einzug): Zieht einen reservierten Betrag ein.
CANCEL (Stornierung): Gibt einen reservierten Betrag wieder frei.
REFUND (Erstattung): Überweist Geld aus einer bereits vollständig erfolgreichen Zahlung (CLOSED_OK) zurück.

Untertransaktionen wechseln nach der Initiierung sofort auf CLOSED_OK oder CLOSED_FAILED, da hier in der Regel keine erneute Kundeninteraktion (wie ein PIN-Eingabe-Redirect) mehr notwendig ist.

4. Lebenszyklus (API-Sicht)

Wenn Sie eigene Frontends bauen und die API nutzen, sind diese vier Kern-Services für den Lebenszyklus relevant:

Start Payment (startPayment): Initiiert die Zahlung. Liefert eine Redirect-URL zurück, auf die der Kunde im Browser geleitet werden muss (z. B. zu PayPal).
Zahlung abschließen (finalizePayment): Dies ist der wichtigste Service nach dem Redirect. Wenn der Kunde von PayPal zurück auf Ihre returnURL oder cancelURL geleitet wird, darf das System diesem Browser-Redirect niemals blind vertrauen (Sicherheitsrisiko). Rufen Sie deshalb finalizePayment serverseitig auf. Das System fragt dann direkt über eine Server-zu-Server-Verbindung den Status beim Zahlungsanbieter ab und setzt die Transaktion von PENDING auf CLOSED_OK oder CLOSED_FAILED.
Capture / Cancel: Services, um auf Basis einer PAYM_RES Haupttransaktion das Geld final einzuziehen oder freizugeben.
Refund Payment (refundPayment): Bucht erfolgreich eingezogenes Geld (aus einer CLOSED_OK Transaktion) zurück.