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

Einfache Kopplung

Terminals über WooCommerce mit einem kurzlebigen Square-Gerätecode koppeln

Webhook-bestätigt

Verifizierte Square-Webhooks bestätigen den Abschluss, mit Live-Status während der Wartezeit

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 Square benachrichtigt Ihre Website über einen signierten Webhook. Der Webhook ist das maßgebliche Abschlusssignal; das POS führt zusätzlich ein Polling durch, sodass der Status während des Wartens aktualisiert wird.

Das bedeutet, dass das Square Terminal-Gerät online und im selben Square-Konto sowie am selben Standort angemeldet sein muss. Außerdem muss Ihre Website öffentlich über HTTPS erreichbar sein, damit Square Webhooks zustellen kann.

Installation

1

Square Terminal for WooCommerce installieren

Installieren Sie das Plugin über WP Admin > POS > Einstellungen > Erweiterungen, 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 > Neu hinzufügen > Plugin hochladen hoch.

2

Square-Einstellungen konfigurieren

1. Navigieren Sie zu WP Admin > WooCommerce > Einstellungen > Zahlungen
2. Suchen Sie Square Terminal in der Liste der Zahlungsmethoden und klicken Sie darauf, um die Einstellungen zu öffnen
3. Wählen Sie die Umgebung (Sandbox für Tests, Production für Live-Zahlungen)
4. Geben Sie Ihren Access Token für die ausgewählte Umgebung (Sandbox oder Production) ein, verfügbar im Square Developer Dashboard
5. Geben Sie Ihre Location ID ein — den Square-Standort, an dem Terminal-Zahlungen entgegengenommen werden
6. Geben Sie Ihren Webhook Signature Key und Ihre Webhook Notification URL ein (siehe nächster Schritt)
7. Klicken Sie auf Einstellungen validieren, um die Anmeldedaten zu überprüfen, und speichern Sie anschließend

Hinweis

Das Square Terminal-Zahlungsgateway muss nicht in den WooCommerce-Einstellungen aktiviert werden. Es wird in einem späteren Schritt speziell für das POS aktiviert.

3

Webhooks in Square einrichten

Square sendet einen signierten Webhook, sobald eine Terminal-Zahlung abgeschlossen ist – dadurch wird die Bestellung als bezahlt markiert.

1. Öffnen Sie im Square Developer Dashboard Ihre Anwendung und navigieren Sie zum Bereich Webhooks
2. Fügen Sie ein Abonnement für das Ereignis terminal.checkout.updated hinzu
3. Setzen Sie die Benachrichtigungs-URL auf die Webhook-Benachrichtigungs-URL, die in den Plugin-Einstellungen angezeigt wird — sie muss exakt übereinstimmen
4. Kopieren Sie den Webhook-Signaturschlüssel in die Plugin-Einstellungen, damit eingehende Ereignisse verifiziert werden können

Wichtig

Die Webhook-Benachrichtigungs-URL in Square muss exakt mit dem Wert in den Plugin-Einstellungen übereinstimmen, und der Webhook-Signaturschlüssel muss korrekt sein. Stimmen diese nicht überein, werden Square-Zahlungen auf dem Gerät abgeschlossen, aber die WooCommerce-Bestellung wird nicht aktualisiert.

4

Square Terminal koppeln

1. Klicken Sie auf derselben Einstellungsseite auf Gerätecode erstellen
2. Ein Kopplungscode wird generiert und angezeigt
3. Melden Sie sich auf Ihrem Square Terminal an und geben Sie den Code auf dem Gerätekopplungsbildschirm ein
4. Nach der Kopplung ist das Terminal mit Ihrem konfigurierten Standort verknüpft. Notieren Sie sich die Geräte-ID — diese wird bei der Zahlungsabwicklung benötigt

Wichtig

Das Terminal muss erfolgreich gekoppelt und online sein, bevor Zahlungen verarbeitet werden können. Stellen Sie sicher, dass die Kopplung abgeschlossen ist, bevor Sie fortfahren.

5

In WCPOS aktivieren

1. Navigieren Sie zu WP Admin > POS > Einstellungen > Checkout
2. Suchen Sie das Square Terminal-Zahlungsgateway in der Liste
3. Aktivieren Sie das Zahlungsgateway für die Verwendung im POS
4. Speichern Sie Ihre Einstellungen

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: Geben Sie die Terminal-Geräte-ID des gekoppelten Terminals ein, das die Zahlung entgegennehmen soll
4. Zahlung starten: Klicken Sie auf Zahlung starten — Square überträgt den Checkout an das Gerät
5. Kundenzahlung: Der Kunde tippt, steckt oder zieht seine Karte am Square Terminal
6. Automatischer Abschluss: Wenn der verifizierte Webhook von Square die Zahlung bestätigt, wird die Bestellung als bezahlt markiert. Der Live-Status wird während des Wartens aktualisiert.

Zahlungssteuerung

Bei Verwendung des Square Terminal-Zahlungsgateways stehen folgende Optionen zur Verfügung:

• Zahlung starten: Eine neue Zahlungsanforderung an das ausgewählte Terminal senden
• Zahlung abbrechen: Eine derzeit am Terminal laufende Zahlung abbrechen
• Zahlungsstatus: Ein Live-Statusbereich zeigt den aktuellen Stand der Zahlung an
• Zahlungsprotokoll: Ein auftragsbezogenes Protokoll erfasst jeden relevanten Square-Schritt und dessen Ergebnis

Bestellverwaltung

• Webhook-autoritative Abwicklung: Bestellungen werden erst als bezahlt markiert, wenn ein verifizierter Square-Webhook die Terminal-Zahlung bestätigt
• 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

API-Zugangsdaten: Access Token, Location ID und Webhook Signature Key aus dem Square Developer Dashboard

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

Öffentliche HTTPS-Website: Die Website muss über HTTPS erreichbar sein, damit Square Webhooks zustellen kann

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 angemeldet sein, und Ihre Website muss Square-Webhooks über HTTPS empfangen können, damit Bestellungen aktualisiert werden.

Unterstützte Terminals

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

Umfang & Einschränkungen

Umfang v0.1

• Diese frühe Version konzentriert sich auf POS-/Bestellzahlungs-Abläufe. 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.

Fehlerbehebung

Häufige Probleme

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 Gerätecode erstellen
• Überprüfen Sie, ob das Terminal online und beim selben Square-Konto und derselben Standort-ID wie das Plugin angemeldet ist
• Überprüfen Sie, ob die Umgebung (Sandbox/Produktion) und das Zugriffstoken mit dem Konto übereinstimmen, bei dem das Terminal angemeldet ist

Einstellungen validieren schlägt fehl

• Überprüfen Sie, ob das Zugriffstoken zur ausgewählten Umgebung passt (ein Sandbox-Token funktioniert nicht in der Produktion und umgekehrt)
• Bestätigen Sie, dass die Standort-ID zu diesem Konto gehört
• Kopieren Sie das Token erneut aus dem Square Developer Dashboard, um versehentlich eingefügte Zeichen auszuschließen

Zahlung wird am Terminal abgeschlossen, aber die Bestellung wird nicht aktualisiert

• Die Webhook-Benachrichtigungs-URL in Square muss exakt mit der Plugin-Einstellung übereinstimmen
• Stellen Sie sicher, dass das Ereignis terminal.checkout.updated im Square Developer Dashboard abonniert ist
• Überprüfen Sie, ob der Webhook-Signaturschlüssel im Plugin mit dem in Square übereinstimmt
• Stellen Sie sicher, dass Ihre Website öffentlich über HTTPS erreichbar ist; überprüfen Sie die Webhook-Zustellversuche im Square Dashboard

Zahlung startet nicht

• Überprüfen Sie, ob eine gültige Terminal-Geräte-ID eingegeben ist und das Gerät gekoppelt und online ist
• Überprüfen Sie, ob das Gerät bei der konfigurierten Standort-ID angemeldet ist
• Überprüfen Sie das Zahlungsprotokoll und die WordPress-Fehlerprotokolle auf Square-API-Meldungen

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

Screenshots

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

• Square-Zugangsdaten, Webhook- und Gerätekopplungs-Konfiguration
• Gateway-Aktivierung in den WCPOS-Einstellungen
• Zahlungsablauf im POS-Checkout