VibeFox Square for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

Shop-Währung: die Währung Ihres Square-Standorts: USD, CAD, AUD, JPY, GBP oder EUR. Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet. Square unterstützt Händler in den USA, Kanada, Australien, Japan, dem Vereinigten Königreich, Irland, Frankreich und Spanien.

Square-Konto: Sie benötigen eine Anwendung im Square Developer Dashboard. Dort kopieren Sie die Application ID und den Access Token (Seite Credentials) sowie die Location ID (Seite Locations). Sandbox und Production haben getrennte Werte. Ein Webhook ist nicht nötig: Das Plugin erhält das Zahlungsergebnis direkt aus der Antwort von Square.

VibeFox-Lizenzschlüssel: Erwerb über vibefox.net. Ein Schlüssel gilt für eine Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Alternativ können Sie den Ordner wcp_square_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Square > Manage oder klicken Sie auf der Seite Plugins unter dem Plugin-Namen auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Lassen Sie Sandbox Mode eingeschaltet und geben Sie die Sandbox-Application-ID, den Access Token und die Location ID ein (siehe Konfiguration). Speichern Sie: Das Plugin prüft die Zugangsdaten bei Square.

6. Schalten Sie Enable/Disable ein und testen Sie eine Zahlung mit den Testkarten aus Squares Anleitung zum Sandbox-Test. Entfernen Sie danach das Häkchen bei Sandbox Mode, geben Sie die Live-Zugangsdaten ein und speichern Sie erneut.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Square. Oberhalb der Felder zeigt die Seite bei eingeschaltetem Sandbox-Modus den Hinweis Square Gateway befindet sich derzeit im SANDBOX-Modus. Es werden keine echten Belastungen vorgenommen.. Sie wird gewarnt, wenn Square aktiviert ist, aber die Application ID, der Access Token oder die Location ID des gewählten Modus fehlt (die Zahlungsart wird dann an der Kasse ausgeblendet), und wenn Square die Shop-Währung nicht verarbeiten kann. In der Liste der Zahlungsarten zeigt Square bei eingeschaltetem Sandbox-Modus das Kennzeichen „Test mode“.

Beim Speichern prüft das Plugin die Zugangsdaten des gewählten Modus bei Square. Sie erhalten eine Fehlermeldung, wenn Square den Access Token ablehnt, wenn die Location ID für diesen Token nicht gefunden wird, wenn die Zugangsdaten nicht geprüft werden konnten oder wenn die Währung des Standorts von der Shop-Währung abweicht. Square kann nur in der Währung des Standorts abrechnen: Das Plugin merkt sich die Währung des geprüften Standorts und blendet die Zahlungsart an der Kasse für jede andere Währung aus; die Einstellungsseite zeigt die Warnung weiterhin an. Außerdem warnt es, wenn eine Sandbox-Application-ID im Live-Modus oder umgekehrt verwendet wird.

General

Enable/Disable: Enable Square Payment Gateway schaltet die Zahlungsart ein oder aus. Standard: off.

Title: der Titel der Zahlungsart, den der Kunde an der Kasse sieht. Standard: Credit / debit card.

Description: die Beschreibung der Zahlungsart, die der Kunde an der Kasse sieht. Standard: Pay securely with your credit or debit card via Square.

Square account

Öffnen Sie das Square Developer Dashboard, wählen Sie Ihre Anwendung und kopieren Sie die Application ID und den Access Token von der Seite Credentials (Sandbox und Production haben getrennte Werte) sowie die Location ID von der Seite Locations. Die Währung des Standorts muss mit Ihrer Shop-Währung übereinstimmen. Die Seite zeigt nur die Zugangsdatenfelder des gewählten Modus: Sandbox-Felder, solange Sandbox Mode eingeschaltet ist, Live-Felder, wenn es ausgeschaltet ist.

Sandbox Mode: Enable sandbox (test) mode. Zahlungen gehen an die Square-Sandbox, und es wird kein echtes Geld belastet. Verwenden Sie Square-Testkarten. Standard: on.

Sandbox Application ID: Ihre Square-Application-ID für die Sandbox (beginnt mit sandbox-sq0idb-).

Sandbox Access Token: Ihr Square-Access-Token für die Sandbox.

Sandbox Location ID: Ihre Square-Location-ID für die Sandbox.

Live Application ID: Ihre Square-Application-ID für den Produktivbetrieb (beginnt mit sq0idp-).

Live Access Token: Ihr Square-Access-Token für den Produktivbetrieb.

Live Location ID: Ihre Square-Location-ID für den Produktivbetrieb.

Advanced

Debug log: Log API requests and responses. Fehler werden immer protokolliert. Schalten Sie die Option ein, um zusätzlich jede Anfrage zu protokollieren, ohne Kartendaten oder Schlüssel. Die Protokolle finden Sie unter WooCommerce > Status > Logs, Quelle wcp_square_gateway. Standard: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. Löscht beim Entfernen des Plugins die Gateway-Einstellungen und die Protokolldateien. Zahlungsdaten der Bestellungen bleiben erhalten. Standard: off.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Credit / debit card) und gibt die Karte in das Square-Kartenformular ein, das unter der Beschreibung angezeigt wird. Im Sandbox-Modus zeigt die Kasse einen Sandbox-Hinweis. Klickt der Kunde auf Place order, wird die Karte im Browser mit Käuferverifizierung (3-D Secure / SCA) tokenisiert: Betrag, Währung und Rechnungskontakt werden an Square übergeben, und die Bank des Kunden kann eine Bestätigung verlangen. Ihr Server erhält nur ein Einmal-Token.

Das Plugin belastet das Token anschließend über die Square Payments API mit der Bestellsumme in der Bestellwährung. Als Referenz dient die Bestell-ID, außerdem gibt es eine Notiz Order # mit der Bestellnummer und dem Namen Ihrer Website sowie die Rechnungs-E-Mail-Adresse. Die Zahlung wird sofort erfasst. Die Bestellung wird erst als bezahlt markiert, nachdem Square sie bestätigt hat: Die Antwort von Square muss eine ABGESCHLOSSENE (COMPLETED) Zahlung über genau die Bestellsumme, Währung, Bestell-ID und Standort ausweisen. Danach gelangt der Kunde zur Bestellbestätigungsseite. Ist die Zahlung nicht COMPLETED oder weicht ein Wert ab, wird die Bestellung mit einer Notiz auf Wartestatus gesetzt, und der Kunde gelangt trotzdem zur Bestellbestätigungsseite.

Pro Bestellung läuft immer nur ein Zahlungsversuch. Klickt der Kunde zweimal oder zahlt in zwei Tabs, zeigt der zweite Versuch Diese Bestellung wird bereits bezahlt. Bitte warten Sie einen Moment und prüfen Sie Ihre E-Mails, bevor Sie es erneut versuchen. Anfragen sind idempotent: Dieselbe Bestellung, dasselbe Token und derselbe Betrag erzeugen niemals eine zweite Zahlung.

Antwortet Square nicht (Netzwerkproblem, Zeitüberschreitung, Serverfehler), wird die Anfrage einmal mit demselben Idempotenzschlüssel wiederholt. Bleibt die Antwort aus, sieht der Kunde Wir konnten keine Bestätigung vom Zahlungsanbieter erhalten. Bitte warten Sie eine Minute und versuchen Sie es erneut. Wurde Ihre Karte bereits belastet, wird die Zahlung erkannt und Sie werden nicht doppelt belastet. Die Bestellnotiz fordert Sie auf, das Square Dashboard zu prüfen. Beim nächsten Versuch sucht das Plugin zuerst bei Square nach der früheren Zahlung dieser Bestellung und schließt die Bestellung mit ihr ab, statt die Karte erneut zu belasten.

Lehnt die Bank die Karte ab, sieht der Kunde eine kurze Meldung anhand des Fehlercodes von Square, zum Beispiel Ihre Karte wurde abgelehnt. Bitte verwenden Sie eine andere Karte oder Zahlungsart., Der Kartenprüfcode (CVV) ist falsch. Bitte prüfen Sie ihn und versuchen Sie es erneut. oder Ihre Bank verlangt eine zusätzliche Verifizierung (3-D Secure). Bitte geben Sie Ihre Karte erneut ein und schließen Sie die Verifizierung ab. Der technische Grund wird in den Bestellnotizen und im Protokoll festgehalten. Der Kunde kann es mit einer anderen Karte erneut versuchen, auch später über die Seite Pay for order.

Die Zahlungsart funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin nimmt nur Kartenzahlungen an, die sofort erfasst werden. Es unterstützt keine gespeicherten Karten oder Kundenprofile, keine WooCommerce Subscriptions oder Vorbestellungen, kein Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH oder Square-Geschenkkarten, keine reinen Autorisierungszahlungen, keine Square-Webhooks und keine Synchronisierung von Produkten oder Lagerbeständen mit Square. Reklamationen (Disputes) werden im Square Dashboard bearbeitet.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Die Bestellung wurde angelegt und noch nicht bezahlt, zum Beispiel nach einer abgelehnten Karte oder einer ausgebliebenen Antwort von Square.

Processing: Square hat eine ABGESCHLOSSENE (COMPLETED) Zahlung in Höhe der Bestellsumme bestätigt. Das ist der übliche WooCommerce-Status nach der Zahlung (Bestellungen mit ausschließlich virtuellen, herunterladbaren Produkten werden zu Abgeschlossen). Die Bestellnotiz zeigt die Square-Zahlungs-ID, die Kartenmarke mit den letzten 4 Ziffern und den Modus (Sandbox oder Live). Die Transaktions-ID ist die Square-Zahlungs-ID; in der Bestellansicht verlinkt sie auf die Zahlung im Square Dashboard.

On hold: Square hat eine Zahlung gemeldet, die nicht COMPLETED ist, oder mit einem anderen Betrag, einer anderen Währung, Referenz oder einem anderen Standort. Die Notiz Square payment needs review zeigt die Zahlungs-ID, den Status und die Beträge. Prüfen Sie Erfassung, Betrag und Währung im Square Dashboard, bevor Sie die Bestellung versenden.

Das Plugin speichert in der Bestellung die Square-Zahlungs-ID, die Kartenmarke und die letzten 4 Ziffern, die Umgebung und den Standort. Kartennummern werden nie gespeichert.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Credit / debit card (die Schaltfläche zeigt Ihren Title). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird an die Umgebung (Sandbox oder Live) und den Standort gesendet, in denen die Zahlung erfolgte. Daher muss der Access Token dieses Modus eingetragen sein. Erstattungsanfragen sind idempotent und werden einmal wiederholt, wenn Square nicht antwortet. Eine Erstattung, die Square annimmt (Status PENDING oder COMPLETED), wird mit der Square-Erstattungs-ID in den Bestellnotizen vermerkt. Lehnt Square sie ab, zeigt WooCommerce den Fehler an, und es wird keine Erstattung erfasst.

Square schließt Erstattungen auf eigener Seite ab. Eine Erstattung, die Square später ablehnt, wird nicht an WooCommerce zurückgemeldet, und im Square Dashboard vorgenommene Erstattungen erscheinen nicht in WooCommerce.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben auf der Seite WooCommerce > Settings > Payments > Square. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel gilt für eine Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Square Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde Diese Zahlungsart ist nicht verfügbar. Bitte wählen Sie eine andere. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Ein Hinweis erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bezahlte Bestellungen bleiben bezahlt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, für Updates und Support ist aber eine Verlängerung nötig. Der Status wird danach automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

Square erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Application ID, der Access Token und die Location ID des aktuellen Modus ausgefüllt sind. Prüfen Sie, ob die Shop-Währung (bzw. die Bestellwährung auf der Seite Pay for order) USD, CAD, AUD, JPY, GBP oder EUR ist und mit der Währung Ihres Square-Standorts übereinstimmt. Die Einstellungsseite zeigt für jedes dieser Probleme eine Warnung an.

Das Kartenformular lädt nicht: Der Kunde sieht Das Kartenformular konnte nicht geladen werden. Bitte laden Sie die Seite neu oder wählen Sie eine andere Zahlungsart. Prüfen Sie, ob Application ID und Location ID zum gewählten Modus gehören (Sandbox-IDs beginnen mit sandbox-). Klickt der Kunde zu früh, erscheint Das Kartenformular wird noch geladen. Bitte warten Sie einen Moment und versuchen Sie es erneut.

Zahlungen werden abgelehnt, obwohl die Karte in Ordnung ist: Die Währung des Standorts muss mit der Shop-Währung übereinstimmen. Speichern Sie die Einstellungen, um das Ergebnis der Zugangsdatenprüfung zu sehen; nach einer erfolgreichen Prüfung wird die Zahlungsart für andere Währungen ausgeblendet.

Square hat den Access Token des gewählten Modus abgelehnt: Der Token gehört zum anderen Modus oder ist falsch. Kopieren Sie ihn erneut von der Seite Credentials Ihrer Anwendung und prüfen Sie Sandbox Mode.

Die Location ID wurde für diesen Access Token nicht gefunden: Kopieren Sie die Location ID von der Seite Locations derselben Anwendung und desselben Modus.

Der Kunde sah „Wir konnten keine Bestätigung vom Zahlungsanbieter erhalten“: Square hat nicht geantwortet. Lesen Sie die Bestellnotiz und prüfen Sie die Zahlungen dieses Standorts im Square Dashboard (Referenz = Bestell-ID). Versucht der Kunde es erneut, sucht das Plugin zuerst nach der früheren Zahlung und schließt die Bestellung mit ihr ab, statt erneut zu belasten.

Die Bestellung ist On hold: Lesen Sie die Notiz Square payment needs review. Die Zahlung war nicht COMPLETED, oder ihr Betrag, ihre Währung oder ihr Standort wich von der Bestellung ab. Prüfen Sie sie im Square Dashboard und versenden Sie dann die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt mit einer Meldung zum Modus fehl: Die Zahlung wurde im Sandbox- oder Live-Modus getätigt, und der Access Token dieses Modus ist nicht eingetragen. Tragen Sie ihn ein und versuchen Sie es erneut.

Andere Fehler: Schalten Sie Debug log ein und sehen Sie unter WooCommerce > Status > Logs nach, Quelle wcp_square_gateway.

Der Lizenzblock zeigt einen Fehler: Befolgen Sie die Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Deinstallation

Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen und die Protokolldateien werden nur entfernt, wenn Delete data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Square-Zahlungs-IDs und Transaktions-IDs.

Square ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Square verbunden noch von Square unterstützt.