Square Terminal Zahlungsgateway

Das Square Terminal Zahlungsgateway ermöglicht es, WooCommerce-Bestellzahlungen direkt aus WCPOS auf Square Terminal-Hardware einzuziehen. Eine Zahlung wird von WooCommerce angefordert und auf einem gekoppelten Square Terminal-Gerät abgeschlossen. Das Ergebnis wird anschließend in die Bestellung zurückgeschrieben.

Funktionen

Hardware-Integration

Zahlungen an gekoppelte Square Terminal-Geräte senden und Kartenzahlungen vor Ort einziehen

Verbinden mit einem Klick

Direkt bei Square autorisieren — kein Access Token, das erstellt oder eingefügt werden muss

Zuverlässiger Abschluss

Zahlungen werden per Polling und einem Hintergrunddienst bestätigt; Webhooks beschleunigen das Ganze

Sichere Transaktionen

PCI-konforme Kartenzahlung vor Ort, abgewickelt über Square-Hardware

Sandbox & Produktion

Validieren Sie zunächst in der Square Sandbox, bevor Sie auf Live-Zahlungen umschalten

Funktionsweise

Im Gegensatz zu browserbasierten SDK-Gateways verwendet Square Terminal die serverseitige Terminal API von Square. Beim Starten einer Zahlung erstellt WooCommerce einen Terminal Checkout für die Bestellung, und Square sendet diesen an das gekoppelte Gerät. Der Kunde bezahlt am Terminal, und das Ergebnis wird in die Bestellung zurückgeschrieben.

Wie eine Zahlung bestätigt wird. Das POS fragt Square während der laufenden Zahlung ab, und ein Hintergrunddienst gleicht alles ab, was die Abfrage verpasst — zum Beispiel bei einem geschlossenen Browser-Tab. Square-Webhooks sind eine optionale Ergänzung, die die Wartezeit verkürzt; sie sind nicht erforderlich, und eine Website ohne sie verliert nie eine Zahlung.

Das Square Terminal-Gerät muss online und im selben Square-Konto sowie am selben Standort wie das Plugin angemeldet sein.

Einrichtung

1

Square Terminal for WooCommerce installieren

Installieren Sie das Plugin über WP Admin > POS > Settings > Extensions, oder laden Sie das neueste Plugin-ZIP-Asset (nicht das GitHub-Quellcode-ZIP oder -Tarball) von der GitHub-Releases-Seite herunter und laden Sie es über Plugins > Add New > Upload Plugin hoch.

2

Mit Square verbinden

1. Navigieren Sie zu WP Admin > WooCommerce > Settings > Payments und öffnen Sie Square Terminal
2. Wählen Sie unter Square account die Environment — Sandbox für Tests, Production für Live-Zahlungen
3. Klicken Sie auf Connect to Square und bestätigen Sie die Berechtigungen, die Square Ihnen anzeigt
4. Wählen Sie die Location ID — den Square-Standort, für den das Terminal Zahlungen entgegennimmt

Wählen Sie die Umgebung vor dem Verbinden. Eine Verbindung gilt immer nur für eine Umgebung; eine Sandbox-Verbindung kann niemals Produktionszahlungen autorisieren.

Verwenden Sie bereits das offizielle WooCommerce-Square-Plugin?

Umgebung und Location ID werden aus dessen Einstellungen vorbelegt. Es werden nur diese beiden Werte gelesen — es werden keine Zugangsdaten zwischen den Plugins geteilt, und Sie müssen sich hier weiterhin verbinden oder ein Access Token angeben.

Möchten Sie lieber Ihr eigenes Access Token verwenden?

Öffnen Sie Advanced settings und fügen Sie dort ein Access Token für die ausgewählte Umgebung ein, statt sich zu verbinden. Alles andere funktioniert identisch.

3

Ihr Square Terminal koppeln

Unter Terminal:

1. Klicken Sie auf Create Device Code — ein Kopplungscode erscheint
2. Öffnen Sie auf dem Square Terminal den Anmeldebildschirm für Gerätecodes und geben Sie den Code ein. Ist das Terminal derzeit bei Square POS oder einer anderen Integration angemeldet, melden Sie sich dort zuerst ab — der Gerätecode-Bildschirm ist nicht erreichbar, solange das Terminal anderweitig in Gebrauch ist.
3. Klicken Sie auf Check for readers, um zu bestätigen, dass es nun unter Paired with this plugin erscheint

Eine leere Liste vor dem Koppeln ist zu erwarten und kein Fehler. Die Geräte-API von Square meldet nur Terminals, die für die Nutzung mit der Terminal API eingerichtet wurden — ein Terminal, auf dem Square POS läuft, erscheint überhaupt nicht, bis ein Gerätecode darauf eingegeben wurde.

4

In WCPOS aktivieren

1. Navigieren Sie zu WP Admin > POS > Settings > Checkout
2. Suchen Sie das Square Terminal-Zahlungsgateway und aktivieren Sie es für das POS
3. Speichern Sie Ihre Einstellungen

Hinweis

Das Kontrollkästchen Enable/Disable auf der WooCommerce-Einstellungsseite steuert ausschließlich den Checkout des Onlineshops. WCPOS verwendet dieses Zahlungsgateway automatisch, sobald es konfiguriert ist — unabhängig davon, ob dieses Kästchen aktiviert ist.

Ein Terminal koppeln

Ein Square Terminal muss mit diesem Plugin gekoppelt werden, bevor ein Kassierer es auswählen kann. Beim Koppeln wird ein Device Code der Terminal API erstellt, und nur darüber kann das Plugin das Gerät ansprechen.

Unter Terminal auf der Einstellungsseite:

• Create Device Code — erzeugt einen Code, der auf dem Terminal einzugeben ist. Er ist kurzlebig; erzeugen Sie bei Ablauf einen neuen.
• Check for readers — listet auf, was Square sehen kann, in zwei Gruppen:
  • Paired with this plugin — an der Kasse auswählbar
  • Other devices Square can see at this location — von einer anderen Anwendung eingerichtet und daher hier erst auswählbar, wenn sie mit diesem Plugin gekoppelt sind
• Validate Settings — prüft die Zugangsdaten und den Standort gegen Square

Warum ein Terminal, das Ihnen gehört, möglicherweise nicht auswählbar ist

Device Codes gehören der Anwendung, die sie erstellt hat. Ein Terminal, das von einer anderen Terminal-API-Integration eingerichtet wurde, erscheint daher unter Other devices Square can see, lässt sich hier aber nicht auswählen. Ein Terminal, auf dem Square POS läuft, erscheint überhaupt nicht.

In beiden Fällen ist die Lösung dieselbe: Melden Sie das Terminal von der Anwendung ab, mit der es derzeit gekoppelt ist, und geben Sie dann einen frischen Create Device Code von hier ein.

Webhooks

Webhooks sind optional. Sie verkürzen die Zeit bis zur Bestätigung einer Zahlung. Polling und der Hintergrunddienst bestätigen jede Zahlung ohnehin, sodass eine Website ohne Webhook-Abonnement weiterhin korrekt funktioniert — die Abwicklung dauert nur etwas länger.

Nicht verfügbar, wenn Sie „Connect to Square“ verwendet haben

Ein Webhook-Abonnement gehört zu einer Square-Anwendung, und um eines hinzuzufügen, wird Zugriff auf diese Anwendung im Square Developer Dashboard benötigt. Wenn Sie sich über Connect to Square verbunden haben, autorisieren Sie die WCPOS-Anwendung statt einer eigenen — es gibt also kein Dashboard, in dem Sie ein Abonnement hinzufügen könnten, und keinen Signaturschlüssel zum Kopieren.

Zahlungen werden trotzdem normal bestätigt — per Polling und über den Hintergrunddienst. Die folgenden Schritte gelten nur, wenn Sie das Plugin mit Ihrem eigenen Access Token unter Advanced settings eingerichtet haben.

So fügen Sie eines mit Ihrer eigenen Square-Anwendung hinzu:

1. Klicken Sie auf der Einstellungsseite unter Terminal → Webhooks auf Copy, um die Webhook-URL zu kopieren
2. Öffnen Sie im Square Developer Dashboard Ihre Anwendung und navigieren Sie zu Webhooks
3. Fügen Sie ein Abonnement für das Ereignis terminal.checkout.updated hinzu und setzen Sie diese URL als Benachrichtigungs-URL ein
4. Kopieren Sie den Webhook Signature Key aus Square in die Advanced settings des Plugins

Die Zeile Webhooks meldet anschließend, ob ein signaturgeprüfter Webhook eingegangen ist und wann.

Die URL muss exakt übereinstimmen

Square signiert jeden Webhook über die Benachrichtigungs-URL, die ihm übergeben wurde. Weicht die URL in Square auch nur um ein Zeichen von der des Plugins ab, scheitert jede Zustellung an der Verifizierung. Verwenden Sie die Schaltfläche Copy, statt sie abzutippen.

Warum dieser Schritt manuell ist

Die Webhook-Subscriptions-API von Square ist auf die Anwendung beschränkt, nicht auf einzelne Verkäufer, und kann nicht mit einem Verkäufer-Access-Token aufgerufen werden. Das Plugin kann das Abonnement daher nicht für Sie anlegen.

Wenn Webhooks nicht mehr verifiziert werden

Die Zeile Webhooks zeigt Not verified yet, wenn unter den aktuellen Einstellungen noch kein Webhook eingegangen und verifiziert wurde. Wenn bereits Zahlungen gelaufen sind, prüfen Sie in dieser Reihenfolge:

1. Der Webhook Signature Key in den Advanced settings stimmt mit dem in Square überein
2. Die Benachrichtigungs-URL in Square stimmt exakt mit der im Plugin angezeigten URL überein
3. Das Ereignis terminal.checkout.updated ist abonniert
4. Ihre Website ist öffentlich über HTTPS erreichbar — prüfen Sie die Zustellversuche im Square Dashboard

Eine Änderung der Umgebung, der Webhook-URL oder des Signaturschlüssels setzt diese Zeile zurück, bis der nächste Webhook eintrifft. Das ist beabsichtigt: Eine unter den alten Einstellungen verifizierte Zustellung sagt nichts über die neuen aus.

Einstellungsreferenz

Die Einstellungsseite ist in der Reihenfolge aufgebaut, in der die Einrichtung abläuft.

Bereich	Enthält
Square account	Umgebung, Connect to Square, Location ID
Terminal	Kopplungssteuerung, Leseliste, Webhook-Status
Checkout behaviour	Belegbildschirm überspringen, Unterschrift erfassen, Debug-Protokolle
Advanced settings	Access Tokens, Webhook-Signaturschlüssel, Webhook-URL-Überschreibung

Advanced settings ist standardmäßig eingeklappt. Dort liegen die manuellen Access Tokens — nur nötig, wenn Sie sich nicht verbinden — sowie der Webhook-Signaturschlüssel. Die Webhook URL override sollte leer bleiben, es sei denn, Ihre öffentliche URL weicht von der ab, die das Plugin ermittelt, zum Beispiel hinter einem Proxy oder bei einer eigenen Domain.

Verwendung

Zahlungen verarbeiten

1. Artikel hinzufügen: Fügen Sie Produkte zu Ihrem Warenkorb im POS hinzu
2. Zahlungsgateway auswählen: Wählen Sie "Square Terminal" als Zahlungsmethode
3. Gerät auswählen: Wählen Sie das gekoppelte Terminal aus der Liste Terminal Device
4. Zahlung starten: Klicken Sie auf Start Payment — Square überträgt den Checkout an das Gerät
5. Kundenzahlung: Der Kunde tippt, steckt oder zieht seine Karte am Square Terminal
6. Abschluss: Der Status wird während des Wartens live aktualisiert, und die Bestellung wird als bezahlt markiert, sobald Square die Zahlung bestätigt

In der Sandbox enthält die Geräteliste die dokumentierten Test-Geräte-IDs von Square, sodass sich jedes Ergebnis — Erfolg, Zeitüberschreitung, offline — ohne Hardware durchspielen lässt.

Zahlungssteuerung

• Start Payment: Eine neue Zahlungsanforderung an das ausgewählte Terminal senden
• Cancel Payment: Eine derzeit am Terminal laufende Zahlung abbrechen
• Check Status: Square sofort nach dem aktuellen Stand fragen
• Release Payment: Ein nicht reagierendes Terminal lösen, damit die Bestellung anders bezahlt werden kann; der aufgegebene Checkout wird weiterhin im Hintergrund abgeglichen
• Payment Log: Ein optionales auftragsbezogenes Protokoll, das jeden Square-Schritt und dessen Ergebnis erfasst

Bestellverwaltung

• Verifizierter Abschluss: Bestellungen werden erst als bezahlt markiert, nachdem die Zahlung gegen das Payment-Objekt von Square verifiziert wurde — niemals aufgrund eines unverifizierten Signals
• Zahlungsverfolgung: Square-Kennungen und ein Zahlungsprotokoll werden in der Bestellung gespeichert, und wichtige Schritte werden in den Bestellnotizen festgehalten
• Belegdruck: Nach erfolgreicher Zahlung werden Standard-POS-Belege erstellt

Voraussetzungen

Square-Konto: Aktives Square-Verkäuferkonto

Square-Standort: Ein Square-Standort und dessen Location ID

Kompatible Hardware: Ein Square Terminal-Gerät, online und am selben Square-Standort angemeldet

Öffentliche HTTPS-Website: Nur erforderlich, wenn Sie Webhooks nutzen möchten; ohne sie werden Zahlungen per Polling bestätigt

WCPOS: Pro-Version erforderlich für den POS-Checkout

Hardware-Kompatibilität

Verbindungsanforderungen

Square Terminal verwendet die serverseitige Terminal-API von Square: Der Checkout wird von Ihrer Website erstellt und über Square an das gekoppelte Gerät übermittelt. Das Terminal muss online und beim selben Square-Konto und -Standort wie das Plugin angemeldet sein.

Unterstützte Terminals

• Square Terminal ✅ — Das dedizierte Kartenterminal von Square für den Kassenbereich

Umfang & Einschränkungen

Aktueller Umfang

• Der Fokus liegt auf POS-/Bestellzahlungs-Abläufen. Die Verfügbarkeit im kundenorientierten Storefront-Checkout ist standardmäßig deaktiviert und muss explizit aktiviert werden.
• Es werden ausschließlich Zahlungen erfasst — Rückerstattungen werden noch nicht unterstützt. Square-Kennungen werden in der Bestellung gespeichert, sodass die Unterstützung für Rückerstattungen später ergänzt werden kann.
• Webhook-Abonnements müssen manuell in Square angelegt werden; siehe Webhooks.

Fehlerbehebung

Häufige Probleme

Die Liste der Terminal-Geräte ist leer

• Das Terminal muss zuerst mit diesem Plugin gekoppelt werden — verwenden Sie Create Device Code und geben Sie den Code auf dem Gerät ein
• Ein über das Square Dashboard oder die Square-POS-App gekoppeltes Terminal erscheint erst, wenn es hier gekoppelt wird
• Klicken Sie auf Check for readers: Erscheint es unter Other devices Square can see, existiert es, ist aber nicht mit diesem Plugin gekoppelt
• Prüfen Sie, ob die Location ID mit dem Standort übereinstimmt, an dem das Terminal angemeldet ist

Gerät lässt sich nicht koppeln

• Stellen Sie sicher, dass der Gerätecode vor Ablauf eingegeben wurde — erstellen Sie bei Bedarf einen neuen mit Create Device Code
• Überprüfen Sie, ob das Terminal online und beim selben Square-Konto und derselben Location ID wie das Plugin angemeldet ist
• Überprüfen Sie, ob die Environment mit dem Konto übereinstimmt, bei dem das Terminal angemeldet ist

Einstellungen validieren schlägt fehl

• Wenn Sie verbunden sind, prüfen Sie, ob die Zeile Square account weiterhin Connected to Square anzeigt; wird zum erneuten Verbinden aufgefordert, ist die Autorisierung abgelaufen
• Bei Verwendung eines Access Tokens prüfen Sie, ob es zur ausgewählten Environment passt — ein Sandbox-Token funktioniert nicht in der Produktion und umgekehrt
• Bestätigen Sie, dass die Location ID zu diesem Konto gehört

Die Zahlung wird am Terminal abgeschlossen, aber die Bestellung wird nur langsam aktualisiert

• Genau dafür sind Webhooks da. Ohne sie wird die Bestellung aktualisiert, sobald das Polling oder der Hintergrunddienst sie das nächste Mal abgleicht
• Prüfen Sie die Zeile Webhooks — steht dort Not verified yet, nachdem bereits Zahlungen gelaufen sind, folgen Sie Wenn Webhooks nicht mehr verifiziert werden
• Die Bestellung geht nie verloren: Der Hintergrunddienst gleicht jede Zahlung ab, die das Polling verpasst

Zahlung startet nicht

• Überprüfen Sie, ob ein Terminal ausgewählt ist und das Gerät gekoppelt und online ist
• Überprüfen Sie, ob das Gerät bei der konfigurierten Location ID angemeldet ist
• Prüfen Sie das Payment Log und WooCommerce > Status > Logs auf Square-API-Meldungen

Es wird gemeldet, dass eine erneute Verbindung zu Square erforderlich ist

Square-Autorisierungen werden automatisch erneuert. Kann eine Erneuerung nicht abgeschlossen werden, beendet das Plugin die Autorisierung, statt sie in einem unbrauchbaren Zustand zu belassen, und die Einstellungsseite fordert Sie zum erneuten Verbinden auf. Klicken Sie auf Reconnect to Square — mehr ist nicht zu ändern.

Hilfe erhalten

Für technischen Support:

• Besuchen Sie das GitHub-Repository, um Probleme zu melden
• Konsultieren Sie die Square Terminal API-Dokumentation für Hardware- und API-Anleitungen
• Kontaktieren Sie den Square-Support bei Konto- und Hardwareproblemen

Protokolle werden unter WooCommerce > Status > Logs mit dem Handle sqtwc geschrieben und erfassen jede Geräteabfrage und jedes Webhook-Ergebnis.

Screenshots

Screenshots werden in einem zukünftigen Update hinzugefügt, um Folgendes zu zeigen:

• Die Bereiche Square account, Terminal und Advanced settings
• Gateway-Aktivierung in den WCPOS-Einstellungen
• Zahlungsablauf im POS-Checkout