Für neue Integrationen empfehlen wir die Block-Integration kombiniert mit Unterstützung der klassischen Gateway-API, für reine Offsite-Redirects reicht die klassische API allein. Die nächsten drei Schritte: Plugin-Grundgerüst anlegen, Pflichtmethoden implementieren, SSL sowie Test-Keys einrichten. Bei Direct-Integrationen mit Kartendaten im eigenen Frontend greifen zusätzlich PCI- und SCA-Pflichten, die den Aufwand deutlich erhöhen.
Kurz gesagt:
- Für Weiterleitungen genügt die klassische Gateway API; integrierte Schnellzahlarten erfordern die Blockintegration, ältere Kassen mit Kurzcode benötigen zusätzlich die klassische Gatewayklasse.
- Für den Start brauchen Sie aktuelle Versionen von WooCommerce und WordPress, PHP 7.4 oder neuer, SSL und Testzugänge; Blockintegrationen benötigen zusätzlich Node.js und npm.
- Fernzahlungen erfordern starke Kundenauthentifizierung mit dynamischer Bindung von Betrag und Empfänger; Direct Gateways unterliegen zusätzlich PCI Vorgaben, weshalb Kartendaten beim Anbieter tokenisiert werden sollten.
- Benachrichtigungsendpunkte müssen jede Signatur prüfen, Wiederholungen ohne doppelte Verarbeitung behandeln und Bestellstatus erst danach ändern; Zugangsdaten gehören nicht in den Quellcode.
- Testen Sie Kassenblöcke, Schnellzahlarten und wiederholte Benachrichtigungen auf einer Testumgebung; ein Start mit einem Teil der Bestellungen senkt das Ausfallrisiko.
Inhaltsverzeichnis
- Voraussetzungen prüfen und Architektur wählen
- Klassisches Gateway in PHP implementieren: Scaffold und Pflichtmethoden
- Block-basierten Checkout anbinden: Server- und Client-Integration
- Sicherheit und regulatorische Pflichten bei Zahlungsintegrationen
- Test- und Deployment-Checkliste vor dem Go-Live
- Warum WERBEEINFACH.de für diese Projekte der richtige Partner ist
- Angebot: Plugin-Entwicklung, Review oder Wartung durch uns
- FAQ
- Quellen
Voraussetzungen prüfen und Architektur wählen
Bevor der erste Code entsteht, lohnt sich ein Blick auf die vier Gateway-Typen, die die WooCommerce Payment Gateway API unterscheidet: Form-, iFrame-, Direct- und Offline-Gateways. Form- und iFrame-basierte Varianten leiten Kunden zum Zahlungsdienstleister weiter oder betten dessen Formular ein, wodurch die Karten- und Kontodaten nie den eigenen Server erreichen. Direct-Gateways verarbeiten diese Daten selbst und ziehen damit erheblich strengere Sicherheitsauflagen nach sich.
Die Entscheidung zwischen klassischer API und Block-Integration hängt vom gewünschten Checkout-Erlebnis ab. Wer native Express-Zahlmethoden, Apple Pay Buttons oder eine moderne, blockbasierte Darstellung benötigt, kommt an der Payment Method Integration API nicht vorbei. Genügt ein einfacher Redirect zum Zahlungsanbieter, bleibt die klassische API die schnellere Lösung mit weniger JavaScript-Aufwand.
Vor dem Start braucht die Entwicklungsumgebung ein paar feste Bausteine:
- Aktuelle WooCommerce- und WordPress-Version in einer lokalen oder Staging-Umgebung.
- PHP 7.4 oder neuer sowie ein aktives SSL-Zertifikat, auch lokal über ein selbst signiertes Zertifikat.
- Node.js und npm für den Build der Block-Assets, falls eine Block-Integration geplant ist.
- Test-Zugangsdaten des gewählten Zahlungsdienstleisters für den Sandbox-Betrieb.
Wer die klassische API und die Block-Variante gleichzeitig unterstützen will, sollte beide Pfade von Anfang an im Projektplan einplanen. Das spart später doppelte Refactorings.
Klassisches Gateway in PHP implementieren: Scaffold und Pflichtmethoden
Der Einstieg erfolgt über den Filter woocommerce_payment_gateways, der die eigene Gateway-Klasse bei WooCommerce registriert. Diese Klasse erweitert WC_Payment_Gateway und übernimmt damit die Grundstruktur, die die WooCommerce Payment Gateway API vorgibt.
Der Aufbau folgt in der Praxis immer derselben Reihenfolge:
- Im
__construct()werdenid,title,method_title,method_descriptionundhas_fieldsgesetzt, danach folgtinit_settings(). init_form_fields()definiert die Admin-Einstellungen, etwa API-Schlüssel oder Sandbox-Modus.payment_fields()rendert zusätzliche Eingabefelder im Checkout, sofern das Gateway Direct-Zahlungen verarbeitet.validate_fields()prüft diese Eingaben vor der Weiterverarbeitung.process_payment($order_id)lädt die Bestellung, stößt die Zahlung beim Anbieter an und setzt den Bestellstatus je nach Ergebnis.- Ein separater Callback-Handler nimmt Webhooks oder IPN-Benachrichtigungen des Anbieters entgegen, prüft die Signatur und verarbeitet die Nachricht idempotent.
Bei Form- und iFrame-Gateways bleibt der Server-Teil vergleichsweise schlank, weil Kartendaten nie das eigene System durchlaufen. Direct-Gateways verlangen dagegen eine durchdachte Fehlerbehandlung: Netzwerkaufrufe zum Zahlungsdienstleister sollten mit Timeout und Retry-Logik laufen, niemals den Checkout-Prozess blockieren und bei Fehlern eine klare, verständliche Meldung an den Kunden liefern.
API-Schlüssel gehören verschlüsselt oder zumindest außerhalb des Versionskontrollsystems abgelegt, idealerweise über die WordPress-Optionen-API mit restriktiven Zugriffsrechten. Webhook-Endpunkte sollten jede eingehende Anfrage gegen eine vom Anbieter signierte Prüfsumme validieren, bevor sie Bestellstatus ändern.
Profi-Tipp: Loggen Sie jede Webhook-Anfrage mit Zeitstempel und Status, auch erfolgreiche. Das spart später Stunden bei der Fehlersuche, wenn ein Zahlungsanbieter Verzögerungen hat.
Wer ein eigenständiges Plugin-Gerüst für diese Struktur sucht, findet in unserem Beitrag zu eigenen Plugins entwickeln eine allgemeine Vorlage für Aufbau und Dateistruktur.
Block-basierten Checkout anbinden: Server- und Client-Integration
Für den Block-Checkout reicht die klassische Gateway-Klasse allein nicht aus. Die Payment Method Integration API verlangt eine zusätzliche serverseitige Klasse, die AbstractPaymentMethodType erweitert und über initialize(), get_payment_method_script_handles() und get_payment_method_data() die nötigen Metadaten an das Frontend reicht.
Die Registrierung dieser Klasse erfolgt über den Hook woocommerce_blocks_payment_method_type_registration, der die Instanz an die PaymentMethodRegistry übergibt. Auf der Client-Seite registriert registerPaymentMethod aus wc.wcBlocksRegistry die Zahlmethode im React-basierten Checkout, für Express-Zahlmethoden wie Wallet-Buttons kommt entsprechend registerExpressPaymentMethod zum Einsatz.
Zentral für eine funktionierende Darstellung ist die canMakePayment-Logik: Sie entscheidet, ob die Zahlmethode im Checkout überhaupt angezeigt wird. Eine fehlerhafte Implementierung führt dazu, dass Express-Buttons gar nicht erscheinen, ein Problem, das in der Praxis häufig für Verwirrung sorgt.
Wesentliche Punkte beim Datenfluss:
- Die eingegebenen
payment_dataaus dem Block-Frontend werden über die Store API auf$_POSTabgebildet, bevorprocess_paymentwie gewohnt aufgerufen wird. - Ältere Themes oder Plugins, die noch den klassischen Shortcode-Checkout nutzen, benötigen weiterhin die klassische Gateway-Klasse als Fallback.
- Der Asset-Build läuft über Node und npm, wobei sich das
dependency-extraction-webpack-pluginzum Entkoppeln von WordPress-eigenen Skripten empfiehlt.
Profi-Tipp: Debuggen Sie Store-API-Anfragen direkt im Browser-Netzwerktyp unter /wc/store/v1/checkout, das zeigt sofort, ob payment_data korrekt ankommt.
Technische Details zur Anbindung und zum Store-API-Ablauf haben wir in unserem Beitrag zur WooCommerce API Anbindung zusammengefasst, Hinweise zum JavaScript-Build finden sich zudem in unserem Artikel zur Gutenberg Block Entwicklung.
Sicherheit und regulatorische Pflichten bei Zahlungsintegrationen
Sobald ein Gateway Fernzahlungsvorgänge auslöst, greift § 55 ZAG mit der Pflicht zur starken Kundenauthentifizierung, kurz SCA. Technisch bedeutet das vor allem eine dynamische Verknüpfung von Zahlungsbetrag und Empfänger, sodass eine Authentifizierung nicht für andere Beträge oder Empfänger wiederverwendet werden kann. Die Deutsche Bundesbank erläutert, dass PSD2 hierfür dynamische TAN-Verfahren und Zwei-Faktor-Mechanismen voraussetzt, was sich direkt auf den Checkout-Flow auswirkt: Der Zahlungsdienstleister steuert die Authentifizierung meist selbst, das Gateway muss aber den Redirect oder das 3D-Secure-Fenster korrekt einbinden.
Starke Authentifizierung ist auch jenseits des reinen Zahlungsvorgangs relevant, etwa beim Schutz von Admin-Zugängen zum Shop-Backend; eine Übersicht zu Verfahren wie WebAuthn und Zwei-Faktor-Authentifizierung gibt einen Einstieg in die technischen Optionen.
Bei Direct-Gateways mit eigener Kartendateneingabe gelten zusätzlich PCI-Anforderungen: Kartendaten sollten nie im eigenen System gespeichert werden, Tokenisierung über den Zahlungsdienstleister reduziert den Scope erheblich, TLS und HSTS sind Pflicht.
Praktische Maßnahmen für den Alltag:
- Webhook-Signaturen bei jeder eingehenden Anfrage prüfen, nie ungeprüft verarbeiten.
- Secrets über Umgebungsvariablen oder ein Secrets-Management-Tool verwalten, nie im Code.
- Content-Security-Policy und CORS-Regeln für Checkout-Seiten definieren und regelmäßig testen.
- Updates von WooCommerce, PHP und Gateway-Abhängigkeiten zeitnah einspielen.
Nichtbeachtung von SCA-Pflichten nach § 55 ZAG kann für Händler und Entwickler zu erheblichen Haftungsrisiken führen, weshalb Compliance von Anfang an Teil der Architektur sein sollte, nicht ein nachträglicher Patch. Wer hier unsicher ist, sollte Sicherheitsmaßnahmen und Betriebshardening parallel zur Gateway-Entwicklung planen, etwa nach unserem Leitfaden zu Sicherheitsmaßnahmen für Onlineshops.
Test- und Deployment-Checkliste vor dem Go-Live
Ein Gateway gehört nie ungetestet in Produktion. Der Testplan läuft typischerweise in dieser Reihenfolge:
- Unit-Tests für
process_paymentund die Callback-Logik mit Mock-Antworten des Zahlungsanbieters schreiben, eingebunden in eine CI-Pipeline. - Checkout-Block, Express-Zahlmethoden und
canMakePayment-Szenarien auf einer Staging-Umgebung durchspielen, inklusive Store-API-Requests. - Webhook-Verarbeitung mit simulierten Wiederholungen testen, um Idempotenz unter realen Bedingungen zu bestätigen.
- Lasttests für gleichzeitige Checkouts fahren, besonders bei Direct-Gateways mit synchronen API-Aufrufen.
- Vor dem Rollout SSL-Zertifikate, Secrets und Feature-Flags prüfen und Monitoring sowie Alerting für Zahlungsfehler aktivieren.
Ein stufenweiser Rollout, etwa zunächst nur für einen Teil der Bestellungen, reduziert das Risiko bei unerwarteten Fehlern erheblich. Auch ein verlässliches Backup-Konzept gehört vor den Go-Live, eine Übersicht zu gängigen Backup-Plugins für WooCommerce hilft bei der Auswahl.
Warum WERBEEINFACH.de für diese Projekte der richtige Partner ist
Wir begleiten Gateway-Integrationen von der Pluginentwicklung bis zur laufenden WordPress Wartung nach dem Go-Live. Unsere Leistungen reichen von individueller Plugin- und Schnittstellenentwicklung über technische Problemlösung bei bestehenden Shops, immer mit transparenter Projektkommunikation und langfristiger Betreuung.
Angebot: Plugin-Entwicklung, Review oder Wartung durch uns
Wenn die eigene Entwicklungskapazität knapp ist oder die Compliance-Anforderungen Kopfzerbrechen bereiten, übernehmen wir die Umsetzung Ihres Zahlungsgateways komplett oder in Teilen.
Konkret bieten wir an:
- Individuelle Pluginentwicklung für klassische und blockbasierte Gateway-Integrationen.
- Komplette WooCommerce Shops inklusive Zahlungsanbindung aus einer Hand.
- Laufende WordPress Wartung für Sicherheitsupdates und Monitoring nach dem Launch.
- Technische WordPress Problemlösung, wenn ein bestehendes Gateway Fehler zeigt.
Melden Sie sich für ein unverbindliches Gespräch zu Ihrem Projekt, wir schauen uns Ihre Anforderungen an und sagen Ihnen ehrlich, was realistisch machbar ist.
FAQ
Was ist der Unterschied zwischen klassischer Gateway-API und Block-Integration?
Die klassische API basiert auf der Klasse WC_Payment_Gateway und reicht für Redirect- oder iFrame-Zahlungen aus. Die Block-Integration nutzt zusätzlich die Payment Method Integration API mit einer serverseitigen AbstractPaymentMethodType-Klasse und clientseitiger JavaScript-Registrierung für den modernen Checkout-Block.
Brauche ich für ein neues Gateway beide Integrationsarten?
Für maximale Kompatibilität empfiehlt sich die Unterstützung beider Wege, da ältere Shortcode-Checkouts weiterhin die klassische Klasse benötigen, während der moderne Checkout-Block die Block-Integration voraussetzt. Wer ausschließlich einen aktuellen Shop ohne Legacy-Theme betreibt, kann sich zunächst auf die Block-Variante konzentrieren.
Welche gesetzlichen Pflichten gelten für ein eigenes Zahlungsgateway?
Bei Fernzahlungsvorgängen verlangt § 55 ZAG eine starke Kundenauthentifizierung mit dynamischer Verknüpfung von Betrag und Empfänger. Direct-Gateways unterliegen zusätzlich PCI-Anforderungen, weshalb Tokenisierung über den Zahlungsdienstleister statt eigener Kartendatenspeicherung die gängige Lösung ist.
Wie teste ich Webhooks eines Zahlungsanbieters zuverlässig?
Webhooks lassen sich mit simulierten, wiederholten Anfragen testen, um Idempotenz unter realen Bedingungen zu prüfen. Jede Anfrage sollte zusätzlich gegen eine vom Anbieter signierte Prüfsumme validiert werden, bevor der Bestellstatus geändert wird.
Was kostet die Entwicklung eines individuellen WooCommerce Payment Gateways?
Der Aufwand hängt stark vom gewählten Gateway-Typ ab: Eine einfache Redirect-Integration ist deutlich schneller umsetzbar als ein Direct-Gateway mit eigener Kartendateneingabe und paralleler Block-Integration. Für ein individuelles Angebot zur Pluginentwicklung sprechen wir die konkreten Anforderungen am besten direkt durch.
Quellen
- WooCommerce Payment Gateway API
- § 55 ZAG — Starke Kundenauthentifizierung
- PSD2 / Was ändert sich bei der Kundenauthentifizierung? — Deutsche Bundesbank
