Die Beschwerde „Die Karte wurde belastet, aber die Bestellung steht noch auf Zahlung ausstehend“ ist das am häufigsten eröffnete Support-Ticket bei der Anbindung virtueller POS-Terminals an WooCommerce. Das Plugin zu aktivieren und den Händlerschlüssel einzutragen, ist der einfache Teil. Schwierig ist Folgendes: die Rückkehr aus 3D Secure prüfen, die Bestellung in den richtigen Status setzen, Erstattungen und Stornos mit dem Bankdatensatz in Einklang halten und am Tagesende den Zahlungseingang mit der Buchhaltung abgleichen. Die folgende Reihenfolge umfasst die Punkte, die E-Commerce-Verantwortliche und WooCommerce-Entwickler vor dem Livegang durchgehen sollten. Sie bezieht sich auf den türkischen Markt mit seinen Bank-POS-Terminals und lizenzierten Zahlungsinstituten.
Direkter Bank-POS oder Zahlungsinstitut
Bei Unternehmens-E-Commerce-Projekten ist die erste Entscheidung, ob die Zahlung direkt über den virtuellen POS einer Bank oder über ein nach dem türkischen Gesetz Nr. 6493 lizenziertes Zahlungsinstitut angenommen wird. Der technische Ablauf wirkt ähnlich. Vertrag, Integrationsaufwand und Tagesgeschäft unterscheiden sich jedoch.
| Kriterium | Direkter Bank-POS | Zahlungsinstitut |
|---|---|---|
| Vertrag | Mit jeder Bank separat | Ein Vertrag, viele Banken |
| Ratenzahlungsaktionen | Nur für Karten dieser Bank | Abhängig von den Vereinbarungen des Instituts |
| Integration | API, spezifisch für den Infrastrukturanbieter der Bank | Meist eine einzige, dokumentierte REST-API |
| Kartendaten | Gemeinsame Zahlungsseite oder Direct Post | Überwiegend gehostetes Formular oder iframe |
| Geldtransfer | Valutaregeln der Bank | Auszahlungskalender des Instituts |
| Abgleich | Separater Bericht pro Bank | Ein Panel, ein Bericht |
Unternehmen mit hohem Umsatz und Verhandlungsmacht gegenüber bestimmten Banken gehen wegen der Provision zum direkten POS. Das hat seinen Preis: Jede neue Bank bedeutet eigene Tests, einen eigenen Hash-Algorithmus, einen eigenen Abgleichsbericht. Drei Banken, drei separate Integrationen. Beim Modell Zahlungsinstitut gibt es nur eine API-Integration; dafür geht das Geld nach dem Auszahlungskalender des Instituts auf das Konto, und die Erstattungsregeln reichen so weit, wie die API des Instituts es zulässt.
Wo die Kartendaten eingegeben werden, bestimmt Ihren PCI-DSS-Aufwand. Wird die Kartennummer vollständig auf einer von Bank oder Institut gehosteten Seite oder in einem iframe erfasst, gilt meist der engste Selbstbewertungsfragebogen (SAQ A). Werden Kartendaten aus einem Formular auf Ihrer Seite direkt an die Bank gesendet (Direct Post), fällt auch die Integrität Ihrer Zahlungsseite in den Geltungsbereich; bei diesem Modell kommt das deutlich umfangreichere SAQ A-EP in Betracht. Laufen Kartendaten über Ihren Server, erweitert sich der Geltungsbereich weiter. Klären Sie mit Ihrem Zahlungsanbieter und anhand der Dokumente des PCI Security Standards Council, welcher Fragebogen für Sie gilt; entscheiden Sie nicht nach Vermutung.
Der 3D-Secure-Zahlungsablauf Schritt für Schritt
EMV 3-D Secure ist das Protokoll, bei dem die kartenausgebende Bank die Identität des Karteninhabers prüft. Aktuelle Umsetzungen nutzen 3DS 2.x; die Bank leitet den Nutzer anhand von Geräte- und Transaktionsdaten zur SMS-Bestätigung weiter oder erteilt eine stille (frictionless) Freigabe. Auf WooCommerce-Seite läuft der typische Ablauf so:
- Der Kunde bestätigt die Bestellung auf der Zahlungsseite; WooCommerce legt die Bestellung im Status
pending(Zahlung ausstehend) an, und der Bestand wird für die in den Einstellungen festgelegte Dauer „Bestand halten“ reserviert. - Die Methode
process_payment()der Gateway-Klasse erstellt eine Anfrage mit Bestellnummer, Betrag, Währung, Ratenzahl sowie Erfolgs- und Fehler-Rücksprungadresse und signiert sie mit dem Händlerschlüssel. - Der Kunde gelangt auf die 3D-Seite der Bank oder des Instituts und schließt die Prüfung ab.
- Die Bank kann das Ergebnis über zwei Kanäle melden: per POST an die Rücksprungadresse über den Browser und per Server-zu-Server-Benachrichtigung (Callback). Welcher Kanal existiert, hängt vom Anbieter ab.
- Bei manchen direkten POS-Modellen ist die 3D-Prüfung allein noch kein Zahlungseingang; ist die Prüfung erfolgreich, ist für die Autorisierung ein zweiter API-Aufruf nötig.
- Nachdem das Ergebnis geprüft ist, wird die Bestellung in den Status
processinggesetzt, die Transaktionsnummer wird in der Bestellung gespeichert, und der Kunde landet auf der Dankesseite.
Der Fehler, den wir in der Praxis am häufigsten sehen, ist das Überspringen des fünften Schritts. Der Entwickler sieht bei der 3D-Rückkehr „erfolgreich“ und betrachtet die Bestellung als bezahlt; da der Autorisierungsaufruf nie erfolgt, wird kein Geld eingezogen.
Callback-Prüfung und Zuordnung des Bestellstatus
Daten an der Rücksprungadresse laufen über den Browser des Kunden. Sie sind nicht vertrauenswürdig. Bei jeder Benachrichtigung werden mindestens diese Prüfungen durchgeführt:
- Signatur-/Hash-Prüfung: Der Hash wird mit den vom Anbieter definierten Feldern und dem Händlerschlüssel neu berechnet und per Vergleich in konstanter Zeit (
hash_equals) geprüft. - Betrag und Währung: Der Betrag in der Benachrichtigung muss dem Wert
get_total()der Bestellung entsprechen. Wird ein Ratenaufschlag berechnet, muss er in der Bestellposition abgebildet sein. - Zuordnung der Bestellung: Die an den Anbieter gesendete Referenz muss mit der Referenz in der Benachrichtigung übereinstimmen, und die Bestellung muss sich in einem Status mit ausstehender Zahlung befinden.
- Wiederholung (Idempotenz): Trifft dieselbe Transaktionsnummer ein zweites Mal ein, wird die Bestellung nicht erneut verarbeitet, sondern nur eine Notiz angelegt.
- Wenn möglich Abfrage-API: Bietet der Anbieter einen Transaktionsabfragedienst, wird das Ergebnis serverseitig ein weiteres Mal abgefragt.
In WooCommerce wird die Server-zu-Server-Benachrichtigung mit der Action woocommerce_api_{name} entgegengenommen; die Adresse hat die Form /?wc-api=name. Das folgende Grundgerüst zeigt den Ablauf; Hash-Felder und Ergebniscodes werden nach der Dokumentation des Anbieters ergänzt.
add_action( 'woocommerce_api_beispiel_pos', function () {
$data = wp_unslash( $_POST );
$order = wc_get_order( absint( $data['order_ref'] ?? 0 ) );
if ( ! $order ) { status_header( 404 ); exit; }
$expected = base64_encode( hash_hmac( 'sha256', $data['order_ref'] . $data['amount'] . $data['status'], STORE_KEY, true ) );
if ( ! hash_equals( $expected, (string) ( $data['hash'] ?? '' ) ) ) {
$order->add_order_note( 'Zahlungsbenachrichtigung mit ungueltiger Signatur abgelehnt.' );
status_header( 400 ); exit;
}
if ( $order->is_paid() ) { echo 'OK'; exit; } // wiederholte Benachrichtigung
if ( wc_format_decimal( $data['amount'], 2 ) !== wc_format_decimal( $order->get_total(), 2 ) ) {
$order->update_status( 'on-hold', 'Betragsabweichung, manuelle Pruefung erforderlich.' );
exit;
}
if ( 'success' === $data['status'] ) {
$order->payment_complete( sanitize_text_field( $data['transaction_id'] ) );
} else {
$order->update_status( 'failed', 'Ergebnis der Bank: ' . sanitize_text_field( $data['error_code'] ?? '' ) );
}
echo 'OK'; exit;
} );
payment_complete() setzt die Bestellung nur dann auf completed, wenn sie ausschließlich aus virtuellen und herunterladbaren Produkten besteht, sonst auf processing, speichert die Transaktionsnummer und löst die Bestandsreduzierung aus. Greifen Sie auf Bestelldaten immer über die Methoden von WC_Order zu. Alter Code, der Post-Meta direkt liest, liefert in einem Shop mit aktivem High-Performance Order Storage (HPOS) leere oder veraltete Werte; er erzeugt keinen Fehler, sondern arbeitet stillschweigend falsch.
Wir empfehlen, die Ergebnisse des Anbieters so den WooCommerce-Status zuzuordnen:
| Ergebnis des Anbieters | WooCommerce-Status | Hinweis |
|---|---|---|
| Autorisierung erteilt | processing | Mit payment_complete() |
| 3D-Prüfung fehlgeschlagen | failed | Kunde kann es erneut versuchen |
| Abweichung bei Betrag oder Signatur | on-hold | Manuelle Prüfung |
| Ergebnis unbekannt / Timeout | pending | Erneute Prüfung über die Abfrage-API |
| Erstattet (vollständig) | refunded | Erstattungsnummer der Bank in der Notiz |
Szenarien für Erstattung, Storno und Teilerstattung
Auf Bankseite gibt es zwei getrennte Vorgänge. Ein Storno erfolgt, bevor die Transaktion in den Tagesabschluss eingeht, und hebt die Autorisierung vollständig auf; auf der Kartenabrechnung erscheint es oft gar nicht. Eine Erstattung gilt dagegen für bereits abgeschlossene Transaktionen, kann vollständig oder teilweise sein, und der Betrag wird dem Karteninhaber innerhalb der bankeigenen Frist gutgeschrieben. Manche Anbieter vereinen beides in einem Endpunkt und entscheiden selbst anhand des Datums; andere verlangen getrennte Aufrufe. Gehen Sie nicht davon aus, ohne die Dokumentation gelesen zu haben.
Wird dem Array supports des Gateways refunds hinzugefügt und die Methode process_refund( $order_id, $amount, $reason ) geschrieben, ruft die Erstattungsschaltfläche in der Bestellansicht die API des Anbieters auf. Zu prüfen ist:
- Prüfen Sie für Teilerstattungen bei Ratenzahlungen die Regel des Anbieters; manche Infrastrukturen schränken Teilerstattungen bei Ratenkäufen ein.
- Schlägt der API-Aufruf fehl, muss die Methode
WP_Errorzurückgeben. Sonst erfasst WooCommerce die Erstattung als erfolgt, während das Geld den Kunden nie erreicht. - Die Option „Manuelle Erstattung“ ändert nur den Bestelldatensatz und ruft die Bank nicht auf. Im Bankpanel durchgeführte Erstattungen müssen in WooCommerce separat erfasst werden.
- Schreiben Sie Erstattungsbetrag und Erstattungsreferenz der Bank in die Bestellnotiz; dort wird beim Abgleich zuerst nachgesehen.
Tagesabgleich
Der Abgleich bestätigt, dass drei Quellen dasselbe aussagen: WooCommerce-Bestellungen, der Transaktionsbericht des Anbieters und der auf dem Bankkonto gutgeschriebene Betrag. Ein täglich laufender Job gleicht die Datensätze des Vortags über die Transaktionsnummer ab und listet Abweichungen auf. Zu suchende Abweichungsarten:
- Transaktionen, die beim Anbieter erfolgreich, in WooCommerce aber
pending,failedodercancelledsind (Geld eingezogen, Bestellung wird aber nicht versendet). - Bestellungen, die in WooCommerce bezahlt erscheinen, im Bericht des Anbieters aber fehlen.
- Betragsabweichungen: Ratenaufschlag, Teilerstattung, Betrag nach Gutschein.
- Im Panel durchgeführte, aber nicht in der Bestellung erfasste Erstattungen.
- Übereinstimmung von Provisions- und Valutaangaben mit der Buchung in der Buchhaltung.
Der Auszug auf WooCommerce-Seite wird mit WP-CLI erstellt; zum Beispiel liefert der Befehl wp wc shop_order list --status=processing --after=2026-11-09T00:00:00 --fields=id,total,transaction_id --user=1 die Liste, die mit dem Bericht des Anbieters verglichen wird (Feldnamen und Parameter entsprechen dem Bestell-Endpunkt der WooCommerce-REST-API). Speichern Sie die Ergebnisse in einer Tabelle, und lassen Sie bei Abweichungen eine Benachrichtigung an den Verantwortlichen gehen. Schaut niemand hin, gilt der Abgleich als nicht durchgeführt. Die allgemeine Gestaltung dieser Kontrollen beschreibt der Leitfaden zu Integrationsmonitoring und Abgleich ausführlich.
Häufige Zahlungsfehler und Lösungen
Zahlung erhalten, aber die Bestellung bleibt auf „Zahlung ausstehend“
An der Konsole sind zuerst die Logs von Webserver und WAF anzusehen. Typische Ursachen: Die Server-zu-Server-Benachrichtigung wird von WAF, einer Cloudflare-Regel oder einer IP-Beschränkung blockiert; die Benachrichtigungsadresse wird in den Seitencache aufgenommen; der Kunde schließt den Browser nach 3D, und das System verlässt sich nur auf die Browser-Rückkehr. Lösung: Halten Sie die Benachrichtigungsadresse außerhalb von Cache und Bot-Schutz, erlauben Sie die ausgehenden IPs des Anbieters, und führen Sie eine geplante Aufgabe aus, die wartende Bestellungen periodisch über die Abfrage-API prüft. Wie Cache-Ausnahmen eingerichtet werden, steht im Beitrag WooCommerce-Cache-Fehler.
Bei der Rückkehr von der Bank gehen Sitzung und Warenkorb des Kunden verloren
Die Rückkehr von der Bankseite ist eine POST-Anfrage von einer anderen Domain. Cookies mit SameSite=Lax werden bei dieser Anfrage nicht mitgesendet, die WooCommerce-Sitzung ist nicht sichtbar. Der Rückkehr-Handler darf sich nicht auf die Sitzung stützen, sondern auf Bestellnummer und Bestellschlüssel (order_key); nach Abschluss wird der Nutzer per GET auf die Dankesseite weitergeleitet.
Eine bezahlte Bestellung wurde automatisch storniert
Nach Ablauf der Dauer „Bestand halten (Minuten)“ werden unbezahlte Bestellungen storniert. Wartet der Kunde lange auf der 3D-Seite, trifft die Freigabe der Bank auf eine bereits stornierte Bestellung. Der Callback-Handler muss diesen Fall erkennen; statt die Bestellung von selbst wieder zu öffnen, sollte er sie auf on-hold setzen und den Bestand prüfen lassen oder den Erstattungsprozess anstoßen.
Dieselbe Bestellung wurde zweimal belastet
Ein Doppelklick auf die Zahlungsschaltfläche oder ein erneuter Versuch über die Zurück-Taste kann zwei Anfragen mit derselben Bestellreferenz erzeugen. Vergeben Sie für jeden Versuch eine eigene Transaktionsreferenz, erzeugen Sie für eine bezahlte Bestellung keine neue Zahlungsanfrage, und melden Sie beim Abgleich mehrere erfolgreiche Transaktionen zur selben Bestellung gesondert.
Testen Sie vor dem Livegang in der Testumgebung diese Szenarien einzeln: erfolgreich, fehlgeschlagen, Timeout, Teilerstattung, wiederholte Benachrichtigung. Ein nicht getestetes Szenario bricht live. Zum Gesamtaufbau des Shops und zur Wahl des Anbieters sehen Sie sich die Seite WooCommerce-E-Commerce-Lösungen an; der Logistikablauf nach der Bestellung ist Thema des Leitfadens WooCommerce-Versandintegration.
Häufig gestellte Fragen
Sollte für den virtuellen POS ein fertiges Plugin oder eine Eigenentwicklung genutzt werden?
Bietet das offizielle oder ein verbreitetes Plugin des Anbieters Callback-Prüfung, Erstattungsunterstützung und HPOS-Kompatibilität, nutzen Sie zuerst dieses. Eine Eigenentwicklung ist sinnvoll, wenn Ratenzahlungs-Routing über mehrere Banken, ERP-spezifische Referenzfelder oder ein vom Plugin nicht unterstütztes Erstattungsmodell benötigt werden.
Ist es möglich, Zahlungen ohne 3D Secure anzunehmen?
Manche Anbieter erlauben Transaktionen ohne 3D Secure unter bestimmten Risikoregeln, dann verbleibt jedoch ein Großteil des Rückbuchungs- und Betrugsrisikos beim Händler. In einem Unternehmens-Shop sollte 3D Secure Standard sein, und Ausnahmen sollten schriftlich mit dem Anbieter festgelegt werden.
Was ist der Unterschied zwischen Storno und Erstattung?
Ein Storno erfolgt, bevor die Transaktion in den Tagesabschluss eingeht, und hebt die Autorisierung vollständig auf. Eine Erstattung erfolgt für bereits abgeschlossene Transaktionen, kann vollständig oder teilweise sein, und der Betrag wird dem Karteninhaber innerhalb der bankeigenen Frist gutgeschrieben. Welches angewendet wird, bestimmen die API-Regeln des Anbieters.
Wie oft sollte abgeglichen werden?
Täglich. Die WooCommerce-Bestellungen des Vortags werden über die Transaktionsnummer mit dem Bericht des Anbieters abgeglichen, Abweichungen werden aufgelistet und dem Verantwortlichen gemeldet. Die Prüfung des auf dem Konto gutgeschriebenen Betrags und der Provision erfolgt separat nach dem Auszahlungskalender des Anbieters.