Payment-Gateway-API-Integration: Ein Entwickler-Leitfaden für DACH-Teams

Der Happy Path ist 5 % der Arbeit

Eine erste Integration wirkt einfach: POST erzeugt eine Charge, Käufer wird umgeleitet, Webhook kommt, Bestellung wird als bezahlt markiert. Das kann man an einem Wochenende demonstrieren.

Produktionsreife ist anders. 95 % des Codes, den Sie ausliefern, und 100 % des Codes, der Incidents verursacht, behandelt:

• Doppelte Requests (Netzwerk-Retries, Browser-Zurück-Taste, Doppelklick).
• Doppelte Webhook-Zustellungen (at-least-once-Semantik).
• Verlorene Webhooks (Firewall, Timeout, laufendes Deployment).
• Teilweise Fehler (Charge erfolgreich, DB-Write gescheitert).
• Race-Conditions zwischen API-Antwort und Webhook.
• Refunds, Disputes und verspätete Zustandsübergänge.
• Sandbox-vs-Produktion-Drift, wenn ein Edge-Case nur im Live-Betrieb feuert.

Bauen Sie von Tag eins an für diese Welt. Unter DORA ist nachvollziehbare Resilienz ohnehin Pflicht.

Authentifizierung: Keys, Secrets, OAuth2

Gateways authentifizieren API-Calls auf drei Arten:

• API-Keys (Secret + Publishable). Am häufigsten. Secret-Key auf dem Server, Publishable-Key im Client für Tokenisierung. Niemals den Secret-Key in den Browser. Rotation planmäßig, spätestens bei Verdacht auf Kompromittierung.
• OAuth2 (Client Credentials). Für plattformartige Gateways, bei denen Ihre App im Namen des Händlers handelt. Kurze Access-Tokens plus Refresh-Tokens. Mehr bewegliche Teile, stärkere Abgrenzung.
• HMAC-signierte Requests. Jeder Request ist mit einem Secret signiert. Passend für Server-zu-Server-Integrationen mit hohen Sicherheitsanforderungen, mehr Boilerplate.

Unabhängig vom Schema: Secrets in einem Secrets-Manager speichern (HashiCorp Vault, AWS Secrets Manager, Hetzner-kompatible KMS-Lösungen oder 1Password Secrets Automation), nie im Code, nie in .env-Dateien im Git. Keys eng skopieren (read-only, invoice-only, refund-only). Quartalsweise rotieren. Unter DSGVO Art. 32 gilt das als Stand der Technik.

Idempotenz: Das Muster gegen Doppelbuchungen

Ein API-Call kann auf drei Arten scheitern: Server hat ihn nie erhalten, Server hat ihn verarbeitet und die Antwort ging verloren, Server hat ihn verarbeitet und einen Fehler zurückgegeben. Der Client kann das nicht unterscheiden. Ein Retry riskiert die zweite Buchung.

Idempotenz löst das. Der Client generiert einen eindeutigen Schlüssel pro logischem Request (eine UUID, gebunden an die Bestellung) und sendet ihn im Idempotency-Key-Header. Der Server speichert den Key mit der Antwort; ein Retry mit identischem Key liefert die ursprüngliche Antwort zurück, ohne die Arbeit erneut auszuführen.

POST /v1/charges
Idempotency-Key: 8b7cfa4d-1e6c-4a12-9a3e-...
Content-Type: application/json

{"amount": 9900, "currency": "eur", "source": "tok_..."}

Umsetzungsregeln:

• Key clientseitig generieren, einmal pro logischem Request, nicht pro Retry.
• Key mit dem Bestelldatensatz persistieren, bevor der Call läuft.
• UUIDv4 oder starker Zufallsstring. Keine Zeitstempel, keine Auto-Inkremente.
• Idempotenz ist nicht ewig: Gateways cachen Keys typischerweise 24 bis 72 Stunden. Danach ist ein neuer Versuch ein neuer Request.
• Retries explizit testen. Selben Key zweimal senden, genau eine Buchung erwarten.

Webhooks: signiert, asynchron, idempotent

Webhooks sind das asynchrone Pendant zur API: Das Gateway ruft Ihren Endpoint auf, wenn ein Ereignis eintritt (Payment abgeschlossen, Dispute geöffnet, Payout gesettled). Falsch gebaut: stille Fehler. Richtig gebaut: das Rückgrat eines verlässlichen Zahlungszustands.

Die Nicht-Verhandelbaren:

1. Signatur prüfen. HMAC-SHA256 über den Raw-Body mit gemeinsamem Secret, verglichen gegen X-Signature-Header. Ungültige Signatur: ablehnen. Nie allein auf Source-IP vertrauen.
2. Schnell 200 zurückgeben. Annahme in unter 500 ms bestätigen. Schwere Arbeit (DB-Writes, E-Mail-Versand, nachgelagerte API-Calls) in eine Queue schieben. Langsame Handler laufen in Timeout und erzeugen zusätzliche Last.
3. Idempotent auf Event-ID. Jeder Webhook trägt eine Event-ID. Vor der Verarbeitung loggen. Duplikat erkannt: 200 zurück, nicht erneut ausführen.
4. Out-of-Order-Events verkraften. Der "Payment succeeded"-Webhook kann vor der API-Antwort ankommen, die die Charge erzeugt hat. State-Machines müssen jede Reihenfolge tolerieren.
5. Replay-Tool bereitstellen. Operator müssen ein spezifisches Event neu feuern können, wenn Ihr Endpoint während eines Deploys nicht erreichbar war.

# FastAPI-Beispiel (Python)
from fastapi import FastAPI, Request, HTTPException
import hmac, hashlib

app = FastAPI()

@app.post("/webhooks/gateway")
async def webhook(request: Request):
    body = await request.body()
    sig = request.headers.get("X-Signature", "")
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(401)
    event = await request.json()
    if await seen_event(event["id"]):
        return {"ok": True}
    await enqueue(event)
    return {"ok": True}

SDKs stehen in Python, Node.js, PHP und Go zur Verfügung. Für die meisten deutschen Shops ist der PHP-SDK (Shopware, WooCommerce) der Einstieg, produktive Backend-Services laufen häufiger in Python oder Go.

Fehlerbehandlung und Retries

Fehler nach Retry-Würdigkeit kategorisieren:

Für retry-fähige Fehler Exponential Backoff mit Jitter. Sinnvolle Folge: 1 s, 3 s, 10 s, 30 s, 2 min, 10 min, dann stoppen und alarmieren. Niemals synchron im Request-Handler retryen, immer in eine Queue schreiben (Celery, RQ, SQS, oder Sidekiq-Äquivalent).

Sandbox, Testkarten, Teststrategie

Jedes seriöse Gateway bietet eine Sandbox mit Testkarten für spezifische Szenarien:

• 4242 4242 4242 4242, generischer Erfolg.
• 4000 0000 0000 0002, generischer Decline.
• 4000 0000 0000 9995, unzureichende Mittel.
• 4000 0027 6000 3184, 3DS2 erforderlich (Pflicht unter PSD2 SCA in der EU).

Test-Disziplin:

1. Jeder Produktionspfad bekommt einen Sandbox-Test. Keine Ausnahmen für "einfachen" Code.
2. Jedes Webhook-Event simulieren, inklusive Out-of-Order und doppelten Zustellungen.
3. Fehler gezielt provozieren: ein Test-Helper, der eine Zahlung mit gewünschtem Decline-Code abspielt.
4. Idempotenz testen: denselben Request zweimal senden, genau eine Buchung erwarten.
5. Refunds, Teil-Refunds und Disputes testen.
6. Chaos-Test: Worker mitten in der Webhook-Verarbeitung killen, bei Neustart sauber durchlaufen lassen.

Besonderheiten von Krypto-Gateway-APIs

Die obigen Muster gelten identisch für Krypto-Gateways. Der Unterschied liegt im Event-Modell, nicht in der Mechanik:

• Invoice-Lifecycle statt Charge-Lifecycle. Rechnung mit EUR-Betrag anlegen, Käufer wählt Asset, Gateway gibt Deposit-Adresse oder Payment-URI zurück. Events: invoice.created, payment.detected, payment.completed, payment.settled, invoice.expired, invoice.underpaid.
• Confirmations als separate Events. Gute Gateways feuern ein Event bei Mempool-Erkennung und ein zweites bei finaler Bestätigung. In der State-Machine getrennt behandeln.
• Keine Karten-Tokens. Kein Vaulting, kein 3DS, keine Network-Tokenization. Ersetzt durch Wallet-Signaturen, die die Wallet des Käufers erzeugt.
• Refunds als Outbound-Transaktionen. Ein Refund ist eine On-Chain-Transaktion aus der Gateway- oder Ihrer eigenen Wallet an die Käufer-Adresse. Planen Sie ein, dass sich die Käufer-Adresse seit der Ursprungszahlung geändert haben kann.
• Off-Ramp-Events. payout.initiated, payout.paid, payout.failed. Gegen den SEPA-Kontoauszug abgleichen, ein Payout bündelt viele Rechnungen.

Der Happy-Path-Code für eine Krypto-Integration ist kürzer als bei Karten, es gibt kein 3DS, kein Vaulting, keine Chargeback-Logik. Die Edge-Cases sind andere, nicht mehr.

Pre-Launch-Integrations-Checkliste

1. Secrets im Secrets-Manager, nie im Code.
2. Idempotency-Keys für jeden POST mit Geldbewegung, clientseitig generiert und persistiert.
3. Webhook-Signaturprüfung aktiv, Unit-Tests gegen manipulierte Payloads.
4. Webhook-Handler antworten unter 500 ms, Verarbeitung in Queue.
5. Event-IDs vor Verarbeitung dedupliziert.
6. State-Machines tolerant gegenüber Out-of-Order-Events.
7. Exponential Backoff mit Jitter für alle retry-fähigen Fehler.
8. Dashboards für fehlgeschlagene Webhooks, Zahlungen und Payouts.
9. Alarme auf Fehlerraten, nicht auf Einzelfehler.
10. Runbooks für die häufigsten Incidents.
11. Lasttest auf 5-faches erwartetes Peak-Niveau.
12. Disaster-Test: Worker mitten in der Verarbeitung killen, saubere Recovery bestätigen.
13. DORA-Dokumentation anlegen: IKT-Risikoinventar, Drittparteien-Register, Incident-Reporting-Prozess.