Provider-Abstraktion ohne SDK (Software Development Kit)-Leckage (Provider Abstraktion Ohne Sdk Leckage)

Im vorherigen Teil haben wir die Grenze zwischen Payment Evidence und Payment State gezogen. Dieser Teil zieht eine noch grundlegendere Grenze: Sollte der Checkout-Orchestrator jemals das SDK eines PSP zu Gesicht bekommen?

Die kurze Antwort: nein. Der Orchestrator sollte genau zwei Dinge wissen: Eine Zahlung wurde angefordert, und ein Ergebnis ist zurückgekommen. Welcher PSP dieses Ergebnis mit welcher SDK-Version erzeugt hat, ist Aufgabe des Provider-Gateways, nicht des Orchestrators.

Checkout Orchestrator
      │  ChargeRequest (semantisch)
      ▼
Provider Gateway
      │  PSP SDK / HTTP Client
      ▼
   PSP A oder PSP B

Diese Grenze wirkt trivial — bis man drei Jahre später einen Provider austauschen muss. Dann entscheidet genau diese Grenze, ob der Wechsel einen Tag oder ein Quartal dauert.

Wo die Begriffe zuerst auftauchen

📦 Provider Gateway
Der einzige Dienst, der das PSP-SDK, die Authentifizierung und providerspezifische Abläufe besitzt.

📦 Semantische Schnittstelle
Der Vertrag, den der Orchestrator tatsächlich sieht — er verweist auf keinen Provider-Typ.

📦 Anti-Corruption Layer
Eine Übersetzungsschicht, die verhindert, dass das Modell eines externen Systems die eigene Domänensprache verschmutzt.

📦 Adapter
Code, der eine providerspezifische Anfrage in eine semantische umwandelt und umgekehrt.

'SDK-Leckage' ist kein Stilproblem: Sobald der ChargeObject-Typ eines PSP im Orchestrator-Code auftaucht, wird ein Providerwechsel nicht mehr zu einer Dateiänderung, sondern zu einem Eingriff in den Kern des Orchestrators.

Warum SDK-Leckage eine stille Schuld ist

Der schnellste Weg, ein Provider-Gateway zu bauen, ist es, die SDK-Objekte des PSP direkt an den Orchestrator weiterzugeben: ChargeResponse importieren, ein Feld lesen, auf einen Status verzweigen. In der ersten Woche ist das schnell. Aber sobald dieser Typ in der Signatur des Orchestrators landet, entsteht eine stille Versionskopplung: Das SDK wird aktualisiert, ein Feld wird umbenannt, und der Orchestrator kompiliert nicht mehr — oder schlimmer, verhält sich stillschweigend falsch.

❌ Orchestrator-Code
if (pspResponse.charges.data[0].outcome.network_status === 'approved') { ... }

✓ Orchestrator-Code
if (chargeResult.status === ChargeStatus.Captured) { ... }

Die zweite Zeile trägt keinen Providernamen. Das Gateway weiß, welches PSP-Feld zu prüfen ist; der Orchestrator kennt nur das semantische Ergebnis.

Warum Karten- und Wallet-Flows eine Schnittstelle, aber keinen Ablauf teilen

Kartenzahlungen sind meist synchron: Eine Anfrage geht raus, und innerhalb weniger hundert Millisekunden kommt ein Autorisierungs- oder Ablehnungsergebnis zurück. Wallet- oder Redirect-Flows (bei denen der Kunde auf die Seite des PSP geleitet wird) sind asynchron: Der erste Aufruf liefert nur einen Pending-Status und eine Redirect-URL; das eigentliche Ergebnis kommt Minuten später per Webhook.

Karten-Flow
  ChargeRequest → [synchroner Aufruf] → ChargeResult (Captured/Declined)

Wallet-Flow
  ChargeRequest → ChargeResult (Pending + redirectUrl)
         ...
  Webhook → ChargeResult (Captured/Failed) [asynchron, später]

Die semantische Schnittstelle bildet beide mit derselben ChargeResult-Form ab; der Unterschied steckt im status-Feld, in dem Pending als legitimer dritter Zustand existiert. Der Orchestrator fragt nie, ob ein PSP einen Redirect nutzt — er fragt nur, ob das Ergebnis schon final oder noch offen ist.

Was die Grenze niemals überschreiten darf

Providerspezifische Fehlercodes, providerspezifische Objekt-IDs (das interne Charge-ID-Format des PSP) und providerspezifische Metadatenstrukturen dürfen die semantische Schnittstelle niemals verlassen. Das Gateway behält diese Information in eigenen Logs und Diagnosedaten; der Orchestrator erhält nur ein Ergebnis, das über seine eigene Correlation-ID verknüpft ist.

Bleibt im Gateway (leckt nie)
  provider_raw_code, provider_object_id, provider_response_headers

Geht an den Orchestrator (semantisch)
  ChargeResult { status, amount, currency, providerRef }

providerRef ist die einzige Ausnahme: eine opake Referenz für Support und Diagnose, auf der niemals verzweigt wird.

Häufig verwechselte Unterschiede

❌ Das SDK in eine Klasse zu verpacken reicht aus
✓ Verpacken löst die Typ-Leckage nicht; das Verhalten bleibt providerspezifisch

❌ Abstraktion bedeutet, ein Interface zu definieren
✓ Abstraktion bedeutet zu entscheiden, was der Orchestrator niemals wissen darf

❌ Mit nur einem PSP ist Abstraktion unnötig
✓ Auch mit einem PSP bringt Abstraktion Testbarkeit und Mockbarkeit

Dünner Wrapper vs. echte Abstraktion

Kriterium	Dünner Wrapper	Semantische Abstraktion
Typ-Leckage	meist vorhanden	keine
Orchestrator betroffen bei PSP-Wechsel	ja	nein
Wer verwaltet Karten-/Wallet-Unterschiede	Orchestrator	Gateway
Testbarkeit	benötigt PSP-Mocks	ein gefälschtes semantisches Ergebnis reicht

Checkliste beim Entwurf der Schnittstelle

1. Taucht in ChargeResult irgendein Providername, Feldname oder Fehlercode direkt auf?
2. Kann der Orchestrator ein Pending-Ergebnis korrekt verarbeiten, ohne zu wissen, ob ein Redirect verwendet wurde?
3. Erfordert ein neuer PSP auch nur eine Zeile Änderung im Orchestrator-Code? Wenn ja, leckt die Abstraktion.
4. Kann das Test-Double des Gateways alle semantischen Zustände erzeugen, ohne den echten PSP anzusprechen?
5. Erreicht irgendein opakes Feld außer providerRef die Entscheidungslogik des Orchestrators?

Diese Ja-Nein-Fragen machen aus 'saubere Architektur' einen messbaren Grenztest statt einer abstrakten Debatte.

Was bleiben soll

1. Das Provider-Gateway ist der alleinige Besitzer des SDK und jedes providerspezifischen Details.
2. Der Orchestrator kennt nur Absicht (ChargeRequest) und semantisches Ergebnis (ChargeResult).
3. Karten- und Wallet-Flows teilen dieselbe Schnittstelle; der Unterschied steckt im Pending-Status.
4. Außer providerRef darf nichts Opakes oder Providerspezifisches die Grenze überschreiten.

Der eigentliche Test einer Abstraktion ist, dass ein neuer Provider niemals den Code des Orchestrators berührt.

Der nächste Teil verschiebt diese Grenze zu Events: Sollten die Webhooks des Gateways den Orchestrator als rohe Provider-Payloads erreichen — oder als semantische Events?