SILVERCLOUD / Fachartikel
Zahlungsbestätigung, der Sie vertrauen können: eine serverseitige Checkliste für Apps und Websites
Ein Kunde tippt auf „Bezahlen“, sieht einen grünen Haken und schließt die App. Ist die Bestellung bezahlt? Wahrscheinlich. Doch wenn es um Geld geht, reicht „wahrscheinlich“ nicht. Der Haken zeigt nur, dass ein Gerät das Ende eines Ablaufs erreicht hat. Ob tatsächlich Geld geflossen ist, weiß der Zahlungsanbieter, und Ihr Server muss es direkt vom Anbieter erfahren, über einen Kanal, den niemand sonst fälschen kann.
Diese Checkliste behandelt Zahlungszustände, serverseitige Bestätigung, sichere Wiederholungen, Erstattungen, Abgleich und Tests, für Karten, E-Wallets und QR-Überweisungen gleichermaßen.
Ein Erfolgsbildschirm ist keine Bestätigung
Nach dem Bezahlen landet der Kunde über eine Rücksprung-URL wieder auf Ihrer Website oder in Ihrer App, oft mit Parametern wie ?status=success&order=1042. Wer diese URL als Beweis nimmt, hat drei Probleme:
- Jeder kann sie ändern.
failedim Browser insuccesszu ändern, dauert Sekunden. - Sie wird womöglich nie geladen. Der Tab wird geschlossen, das Netz bricht ab oder die Banking-App springt nicht zurück, und Ihr Server erfährt nie von einer erfolgreichen Zahlung.
- Sie kann vor dem Geld ankommen. Manche Zahlungsarten, vor allem Banküberweisungen, bleiben ausstehend, nachdem der Kunde seinen Teil erledigt hat.
Die Rücksprungseite sollte „Zahlung wird bestätigt“ anzeigen und Ihren eigenen Server fragen, der nur geprüften Quellen vertraut. Der Client entscheidet nie, ob eine Bestellung bezahlt ist.
Die Zustände einer Zahlung
Modellieren Sie die Zahlung explizit statt mit einem einzigen paid-Flag:
- Angelegt: beim Anbieter registriert, noch nicht bezahlt.
- Ausstehend: Der Kunde hat gehandelt oder eine Überweisung läuft; das Ergebnis ist nicht endgültig.
- Erfolgreich: Der Anbieter bestätigt den Zahlungseingang.
- Fehlgeschlagen: abgelehnt, abgebrochen oder blockiert.
- Abgelaufen: Das Zahlungsfenster ist ohne Ergebnis verstrichen.
- Teilweise erstattet und erstattet: Geld nach dem Erfolg teilweise oder vollständig zurückgezahlt.
Bei Karten kann ein Zustand „autorisiert, aber noch nicht eingezogen (Capture)“ hinzukommen und später Rückbelastungen (Disputes). Halten Sie die erlaubten Übergänge im Code fest: Angelegt kann zu ausstehend werden; angelegt oder ausstehend kann zu erfolgreich, fehlgeschlagen oder abgelaufen werden; erfolgreich kann zu teilweise erstattet oder erstattet werden, und eine teilweise erstattete Zahlung kann weiter erstattet werden; nichts kehrt zu angelegt oder ausstehend zurück. Jede andere Änderung ist ein Fehler oder ein Fall für eine manuelle Prüfung.
Serverseitig bestätigen, aus einer prüfbaren Quelle
Es gibt zwei vertrauenswürdige Quellen, und solide Integrationen nutzen beide.
Signierte Webhooks. Der Anbieter ruft bei einem Ereignis Ihren Endpunkt auf, und die meisten Anbieter signieren jede Anfrage mit einem gemeinsamen Geheimnis: typischerweise ein HMAC-SHA256 über den Raw Body, oft zusammen mit einem Zeitstempel. Ihr Handler sollte:
- den Raw Body genau so lesen, wie er ankommt. JSON zu parsen und neu zu serialisieren, kann Leerzeichen, Escaping oder die Reihenfolge der Schlüssel ändern, und die Signatur passt nicht mehr.
- den HMAC berechnen und in konstanter Zeit mit dem Header vergleichen. Ein gewöhnlicher Stringvergleich bricht beim ersten abweichenden Zeichen ab, und dieser Zeitunterschied kann Informationen über die erwartete Signatur verraten.
- Zeitstempel außerhalb eines kurzen Fensters ablehnen, häufig fünf Minuten, damit eine abgefangene Anfrage nicht später erneut eingespielt werden kann; eine Wiederholung innerhalb des Fensters wird durch die Deduplizierung nach Ereignis-ID abgefangen.
- Betrag, Währung und Bestellreferenz mit der angelegten Bestellung abgleichen. Eine gültige Signatur beweist, wer die Nachricht gesendet hat, nicht aber, dass der richtige Betrag für die richtige Bestellung gezahlt wurde. Speichern Sie Beträge als Ganzzahlen in der kleinsten Währungseinheit, nie als Gleitkommazahlen.
Die API des Anbieters. Ihr Server fragt die Zahlung mit Ihrem geheimen Schlüssel per ID ab. Das deckt verspätete oder verlorene Webhooks ab; manche Teams behandeln jeden Webhook nur als Signal, den aktuellen Stand abzurufen.
API-Schlüssel und Webhook-Geheimnisse bleiben auf dem Server, nicht in der App und nicht im Repository, und lassen sich ohne Ausfallzeit rotieren.
Idempotenz: dasselbe Ereignis zweimal ändert nichts
Die meisten Anbieter stellen Webhooks „mindestens einmal“ zu: Läuft Ihr Endpunkt in einen Timeout oder antwortet er mit einem Fehler, kommt das Ereignis erneut, manchmal mehrfach. Duplikate sind normal, also muss die Verarbeitung idempotent sein.
- Nach Ereignis-ID deduplizieren. Speichern Sie verarbeitete Ereignis-IDs mit einer Eindeutigkeitsbedingung (Unique Constraint), dann ändert eine wiederholte Zustellung nichts.
- Eine Transaktion, ein Update. Ereignis-ID und Statusänderung der Bestellung gehören in dieselbe Datenbanktransaktion; schlägt etwas fehl, wird beides zurückgerollt und die Wiederholung beginnt sauber. Machen Sie das Update bedingt (
WHERE status = 'pending'), damit ein Webhook und eine gleichzeitig eintreffende API-Prüfung die Bestellung nicht beide abwickeln. - Idempotenzschlüssel für neue Zahlungen und Erstattungen. Unterstützt der Anbieter sie, leiten Sie den Schlüssel aus Ihrer eigenen Versuchs-ID ab; ein Retry nach einem Timeout liefert dann das ursprüngliche Ergebnis, statt doppelt abzubuchen. Wenn nicht, speichern Sie zuerst Ihren eigenen Datensatz mit einer eindeutigen Referenz und prüfen Sie diese vor jedem Retry.
- Ereignisse in falscher Reihenfolge. Die Zustellreihenfolge ist in der Regel nicht garantiert; ein Erfolgsereignis kann nach einem Erstattungsereignis eintreffen. Entscheiden Sie anhand Ihrer Übergangsregeln, nicht anhand des zuletzt eingetroffenen Ereignisses, und rufen Sie im Zweifel den aktuellen Stand ab.
- Backoff. Wiederholen Sie bei Timeouts, Verbindungsfehlern sowie 429- und 5xx-Antworten mit exponentiellem Backoff, Jitter und einer Obergrenze an Versuchen. Validierungsfehler werden nicht wiederholt.
- Ein Timeout heißt „unbekannt“, nicht „fehlgeschlagen“. Die Belastung kann durchgegangen sein; klären Sie es per Abfrage.
- Ablauf nach Zeitplan. Ein Job findet Zahlungen, die nach ihrem Fenster noch ausstehen, fragt beim Anbieter nach und markiert sie erst dann als abgelaufen. Ein Erfolg nach dem Ablauf, wie er bei Banküberweisungen vorkommt, geht nach einer vorab vereinbarten Regel in die Prüfung oder wird erstattet.
Beantworten Sie Webhooks schnell: speichern, committen, 2xx zurückgeben und langsame Arbeit wie E-Mails und Versand in eine Queue legen. Langsame Handler verursachen Timeouts, und Timeouts verursachen Duplikate.
So sieht es im Code aus
Ein minimaler Handler in TypeScript für Node.js und PostgreSQL. Header-Namen, Signaturkodierung und der signierte String unterscheiden sich je nach Anbieter; die Struktur bleibt gleich.
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app
export async function handlePaymentWebhook(req: Request): Promise<Response> {
const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
const timestamp = req.headers.get("x-signature-timestamp") ?? "";
const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
return new Response("invalid signature", { status: 400 });
}
const event = JSON.parse(raw.toString("utf8"));
const db = await pool.connect();
try {
await db.query("BEGIN");
// event_id is the primary key: a repeated delivery inserts nothing.
const inserted = await db.query(
"INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
// Only pending -> paid, and only if amount and currency match the order.
const paid = await db.query(
`UPDATE orders SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
[event.data.order_id, event.data.amount, event.data.currency]);
if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
}
await db.query("COMMIT");
return new Response("ok");
} catch {
await db.query("ROLLBACK");
return new Response("retry later", { status: 500 }); // the provider retries
} finally {
db.release();
}
}Passt keine ausstehende Bestellung (bereits bezahlt, abgelaufen oder anderer Betrag), landet das Ereignis in einer Prüftabelle, statt zu verschwinden.
Erstattungen, Abgleich und Audit-Trail
Erstattungen sind eigene Datensätze, die mit der Zahlung verknüpft sind und eigene Zustände haben: Auch eine Erstattung kann ausstehen oder fehlschlagen. Teilerstattungen dürfen in Summe nie den eingezogenen Betrag übersteigen. Senden Sie Erstattungsanfragen mit Idempotenzschlüssel und ändern Sie den Bestellstatus erst, wenn der Anbieter bestätigt.
Der tägliche Abgleich fängt auf, was allem anderen entgeht. Laden Sie den Transaktions- oder Abrechnungsbericht des Anbieters für den Vortag, ordnen Sie jede Zeile über die Transaktions-ID des Anbieters Ihren Datensätzen zu und vergleichen Sie Betrag, Währung und Status. Typische Abweichungen:
- Beim Anbieter bezahlt, bei Ihnen ausstehend: ein verlorener Webhook und ein Kunde, der bezahlt hat und noch wartet.
- Bei Ihnen bezahlt, beim Anbieter unbekannt: ein Fehler oder Missbrauch, der dringendste Fall.
- Abweichender Betrag oder Status: eine nicht erfasste Teilerstattung oder verwechselte Brutto-, Gebühren- und Nettobeträge.
Abweichungen kommen in eine Differenzen-Queue mit einer verantwortlichen Person und einer Lösungsnotiz; nichts wird stillschweigend korrigiert. Achten Sie auf die Cut-off-Zeit des Berichts: Eine Zahlung kurz vor Mitternacht kann auf beiden Seiten an unterschiedlichen Tagen landen.
Audit-Trail. Bewahren Sie jeden Webhook roh auf, mit Headern und Prüfergebnis, damit Sie ihn erneut abspielen können, dazu einen nur fortschreibbaren (append-only) Verlauf der Statusänderungen: von, nach, wann und durch welches Ereignis, welchen Job oder welche Person. Protokollieren Sie nie Geheimnisse oder vollständige Kartennummern; mit einer vom Anbieter gehosteten Zahlungsseite oder eingebetteten Zahlungsfeldern erreichen Kartennummern Ihre Server gar nicht erst.
Alarme sollten auslösen bei gehäuften Signaturfehlern, Verarbeitungsfehlern, Zahlungen, die in „ausstehend“ hängen, fehlgeschlagenen Erstattungen, Abweichungen im Abgleich und Einbrüchen der Erfolgsquote.
Testen Sie die Fehler, nicht nur den Happy Path
Nutzen Sie die Sandbox oder den Testmodus des Anbieters mit Testschlüsseln, und dann:
- Webhooks erneut abspielen. Speichern Sie echte Sandbox-Ereignisse als Fixtures; senden Sie eines zweimal, kehren Sie die Reihenfolge um, ändern Sie ein Byte im Body, verwenden Sie einen alten Zeitstempel.
- Fehler einschleusen. Beenden Sie den Prozess nach dem Commit, aber vor der 2xx-Antwort: Der Anbieter sendet erneut, und nichts darf doppelt passieren. Nehmen Sie die Datenbank für eine Minute vom Netz. Verzögern Sie Aufrufe an den Anbieter, bis Ihre Timeouts greifen.
- Den Client zweckentfremden. Zweimal schnell auf „Bezahlen“ tippen, den Browser vor der Weiterleitung schließen, die Rücksprung-URL mit gefälschten Parametern öffnen.
Checkliste vor dem Livegang
- Der Status „bezahlt“ entsteht nur durch einen verifizierten Webhook oder eine serverseitige API-Abfrage.
- Signaturen werden über den Raw Body in konstanter Zeit geprüft; veraltete Zeitstempel werden abgelehnt.
- Betrag, Währung und Bestellreferenz werden mit der Bestellung abgeglichen.
- Ereignis-IDs sind eindeutig; Duplikate liefern 2xx ohne Nebenwirkungen.
- Ereignisdatensatz und Statusänderung werden in einer Transaktion committet, mit bedingtem Update.
- Das Anlegen von Zahlungen und Erstattungen nutzt Idempotenzschlüssel oder eine Abfrage über die eigene Referenz.
- Übergänge sind im Code definiert; verspätete Ereignisse können eine Bestellung nicht zurücksetzen.
- Der Webhook antwortet innerhalb des Anbieter-Timeouts; langsame Arbeit läuft über eine Queue.
- Ausgehende Aufrufe haben Timeouts und begrenzte Retries mit Backoff und Jitter.
- Ausstehende Zahlungen laufen nach Zeitplan und nach einer Statusabfrage ab; späte Erfolge haben einen festgelegten Weg.
- Teilerstattungen können den eingezogenen Betrag nicht übersteigen.
- Der Abgleich läuft täglich, und jede Abweichung hat eine verantwortliche Person.
- Rohe Webhooks und Statusverlauf werden aufbewahrt; Logs enthalten keine Geheimnisse oder vollständigen Kartennummern.
- Alarme decken Signaturfehler, Verarbeitungsfehler, hängende Zahlungen und Abweichungen im Abgleich ab.
silvercloud ist ein externes Entwicklungsteam. Für Partnerunternehmen bauen wir diese Schicht in Apps und Websites ein, vom Checkout über Webhooks bis zu Erstattungen und Abgleich, und entwickeln Payment-Gateway-Systeme nach ihren Anforderungen; anschließend übergeben wir die Arbeit, damit das Team des Partners sie betreibt. Wenn Sie eine Zahlungsintegration planen, senden Sie uns Ihren Brief über silvercloud.city.