# Square Terminal Zahlungsgateway

Das Square Terminal Zahlungsgateway ermöglicht es, WooCommerce-Bestellzahlungen direkt aus WCPOS auf [Square Terminal](https://squareup.com/hardware/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[​](#features "Direkter Link zu 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[​](#how-it-works "Direkter Link zu 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[​](#installation "Direkter Link zu 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](https://github.com/wcpos/square-terminal-for-woocommerce/releases) 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](https://developer.squareup.com/apps)
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](https://developer.squareup.com/apps) 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[​](#usage "Direkter Link zu Verwendung")

### Zahlungen verarbeiten[​](#processing-payments "Direkter Link zu 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[​](#payment-controls "Direkter Link zu 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[​](#order-management "Direkter Link zu 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[​](#requirements "Direkter Link zu 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[​](#hardware-compatibility "Direkter Link zu 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[​](#supported-terminals "Direkter Link zu Unterstützte Terminals")

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

## Umfang & Einschränkungen[​](#scope-and-limitations "Direkter Link zu 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[​](#troubleshooting "Direkter Link zu Fehlerbehebung")

### Häufige Probleme[​](#common-issues "Direkter Link zu 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[​](#getting-help "Direkter Link zu Hilfe erhalten")

Für technischen Support:

* Besuchen Sie das [GitHub-Repository](https://github.com/wcpos/square-terminal-for-woocommerce), um Probleme zu melden
* Konsultieren Sie die [Square Terminal API-Dokumentation](https://developer.squareup.com/docs/terminal-api/overview) für Hardware- und API-Anleitungen
* Kontaktieren Sie den Square-Support bei Konto- und Hardwareproblemen

## Screenshots[​](#screenshots "Direkter Link zu 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