VibeFox Square for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Währung: Die Warenkorbwährung muss die Währung Ihres Square-Standorts sein: 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 Modul erhält das Zahlungsergebnis direkt aus der Antwort von Square.

VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel gilt für eine Domain.

Installation

1. Gehen Sie im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Square Gateway in der Modulliste und klicken Sie auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Lassen Sie Sandbox Mode eingeschaltet und geben Sie die Sandbox-Application-ID, den Access Token und die Location ID ein (siehe Konfiguration). Klicken Sie auf Save: Das Modul prüft die Zugangsdaten bei Square.

5. Schalten Sie Enable/Disable ein, speichern Sie und testen Sie eine Zahlung mit den Testkarten aus Squares Leitfaden zum Sandbox-Test. Schalten Sie danach Sandbox Mode aus, geben Sie die Produktionsdaten ein und speichern Sie erneut.

Bei der Installation legt das Modul den Bestellstatus Square payment on hold an. PrestaShop erlaubt einem neuen Zahlungsmodul die Währungen, die zum Installationszeitpunkt aktiven Länder und die Kundengruppen. Prüfen Sie sie, und aktivieren Sie später hinzugefügte Länder unter Payment > Preferences.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Square Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern zeigt die Seite bei aktivem Sandbox-Modus Square Gateway befindet sich derzeit im SANDBOX-Modus. Es werden keine echten Zahlungen abgebucht. an. Sie warnt, 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), wenn Square die Standardwährung Ihres Shops nicht verarbeiten kann und wenn die Währung Ihres Square-Standorts davon abweicht.

Beim Speichern prüft das Modul die Zugangsdaten des gewählten Modus bei Square. Die Einstellungen werden in jedem Fall gespeichert. Eine Warnung erscheint, 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 abbuchen: Das Modul merkt sich die Währung des geprüften Standorts und blendet die Zahlungsart für Warenkörbe in jeder anderen Währung aus. Es warnt außerdem, wenn eine Sandbox-Application-ID im Live-Modus verwendet wird oder umgekehrt.

Square

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. Er ist auch der Name der Zahlungsart, der in der Bestellung gespeichert wird. Standard: Credit / debit card. Pflichtfeld.

Description: die Beschreibung der Zahlungsart, die der Kunde an der Kasse sieht. Standard: Pay securely with your credit or debit card via Square. Im Sandbox-Modus wird (SANDBOX MODE) angehängt.

Square-Konto

Öffnen Sie das Square Developer Dashboard (der Abschnitt enthält einen Link), 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 der Shop-Währung übereinstimmen. Die Seite zeigt nur die Zugangsfelder des gewählten Modus: die Sandbox-Felder, solange Sandbox Mode eingeschaltet ist, und die Live-Felder, wenn es ausgeschaltet ist. Beide Sätze bleiben gespeichert.

Sandbox Mode: Zahlungen gehen an die Square-Sandbox, und es wird kein echtes Geld abgebucht. 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 die Produktion (beginnt mit sq0idp-).

Live Access Token: Ihr Square-Access-Token für die Produktion.

Live Location ID: Ihre Square-Location-ID für die Produktion.

Gespeicherte Access Tokens werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Gespeichert — leer lassen, um ihn zu behalten. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved secrets: Setzen Sie bei einem Access Token ein Häkchen und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Erweitert

Debug log: Fehler und Warnungen werden immer protokolliert. Schalten Sie es ein, um zusätzlich jede Anfrage und Antwort ohne Kartendaten oder Schlüssel in logs/wc_sqg_debug.log.php im Modulordner zu protokollieren. Die Datei lässt sich aus dem Web nicht öffnen. Standard: off.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Delete data on uninstall: Ist die Option eingeschaltet, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und die Protokolldateien. Die Square-Zahlungen und -Erstattungen der Bestellungen sowie der Bestellstatus Square payment on hold bleiben immer erhalten. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit / debit card) und gibt die Karte im Square-Kartenformular ein, das unter der Beschreibung angezeigt wird. Wenn der Kunde die Bestellung absendet, wird die Karte im Browser mit Käuferverifizierung (3-D Secure / SCA) tokenisiert: Warenkorbbetrag, Währung und Rechnungsadresse werden an Square übergeben, und die Bank des Kunden kann eine Bestätigung verlangen. Ihr Shop erhält nur ein Einmal-Token.

Anschließend belastet das Modul das Token über die Square Payments API mit dem Warenkorbbetrag in der Warenkorbwährung, mit der Warenkorb-ID als Referenz, einer Notiz Cart # mit der Warenkorbnummer und Ihrem Shopnamen sowie der E-Mail-Adresse des Kunden. Die Zahlung wird sofort erfasst. Die Bestellung gilt erst als bezahlt, nachdem Square sie bestätigt hat: Die Antwort von Square muss eine COMPLETED-Zahlung über genau den Warenkorbbetrag, die Währung, die Warenkorb-ID und den Standort zeigen. Dann wird die Bestellung mit Payment accepted angelegt, und der Kunde sieht die Standard-Bestellbestätigungsseite mit Ihre Kartenzahlung ist eingegangen. und einem Link zum Square-Beleg. Ist die Zahlung nicht COMPLETED oder weicht ein Wert ab, wird die Bestellung mit Square payment on hold angelegt, und die Seite zeigt Ihre Kartenzahlung ist eingegangen und wird geprüft. Wir aktualisieren Ihre Bestellung, sobald die Prüfung abgeschlossen ist.

Pro Warenkorb läuft immer nur ein Zahlungsversuch gleichzeitig. Klickt der Kunde zweimal oder zahlt in zwei Tabs, sieht 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: derselbe Warenkorb, dasselbe Kartentoken und derselbe Betrag erzeugen nie eine zweite Zahlung, und ein Warenkorb, der bereits eine Bestellung hat, wird nie erneut belastet.

Antwortet Square nicht (Netzwerkproblem, Zeitüberschreitung, Serverfehler), wird die Anfrage einmal mit demselben Idempotenzschlüssel wiederholt. Bleibt die Antwort aus, sucht das Modul sofort nach der Zahlung dieses Warenkorbs bei Square. Wird sie gefunden, wird die Bestellung damit angelegt. Wird keine Zahlung gefunden, bleibt der Kunde an der Kasse mit 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 Ihnen wird nicht doppelt berechnet. Der nächste Versuch sucht zuerst erneut nach der früheren Zahlung. Kann Square auch für die Suche nicht erreicht werden, wird die Bestellung ohne Zahlung mit Square payment on hold angelegt, mit einer Notiz, dass die Karte möglicherweise belastet wurde. Die Bestätigungsseite zeigt dann Wir konnten keine Bestätigung Ihrer Kartenzahlung von Square erhalten. Bitte prüfen Sie Ihre E-Mails und Ihre Kartenabrechnung, bevor Sie erneut bezahlen, oder kontaktieren Sie uns.

Lehnt die Bank die Karte ab, wird keine Bestellung angelegt, und der Kunde bleibt an der Kasse mit einer kurzen Meldung gemäß dem Fehlercode von Square, zum Beispiel Ihre Karte wurde abgelehnt. Bitte verwenden Sie eine andere Karte oder Zahlungsart., Der Sicherheitscode (CVV) der Karte 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 Warenkorb bleibt erhalten, und der Kunde kann es mit einer anderen Karte erneut versuchen. Der technische Grund wird im Protokoll gespeichert.

Das Modul nimmt nur Kartenzahlungen an, die sofort erfasst werden. Es hat keine gespeicherten Karten oder Kundenprofile, keine Abonnements, 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 Lagerbestand mit Square. Streitfälle werden im Square Dashboard verwaltet.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Die Karte wurde abgelehnt, oder die Antwort von Square ging verloren und es wurde keine Zahlung gefunden. Nur der Warenkorb existiert.

Payment accepted: Square hat eine COMPLETED-Zahlung über den Warenkorbbetrag bestätigt. Die Zahlung wird mit der Square-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlungs-ID, die Kartenmarke mit den letzten 4 Ziffern und den Modus (sandbox oder live).

Square payment on hold: Square hat mit einer Zahlung geantwortet, die nicht COMPLETED ist (zum Beispiel APPROVED), oder mit einem abweichenden Betrag, einer abweichenden Währung, Referenz oder einem abweichenden Standort. Die Notiz Zahlung bei Square prüfen zeigt Zahlungs-ID, Status und Beträge. Eine COMPLETED-Zahlung wird mit dem Betrag, den Square abgebucht hat, auf der Bestellung erfasst. Dieser Status wird auch verwendet, wenn sich der Warenkorb während der Zahlung geändert hat und wenn die Antwort von Square ausblieb und nicht geprüft werden konnte (dann wird keine Zahlung erfasst). Prüfen Sie die Zahlung im Square Dashboard, bevor Sie die Bestellung versenden.

Refunded: Die Zahlung wurde über das Modul vollständig erstattet.

Geht eine zweite Zahlung für einen Warenkorb ein, der bereits eine Bestellung hat, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, sie zu prüfen und das Duplikat im Square Dashboard zu erstatten.

Square-Block

Die Bestellseite zeigt einen Block Square mit der Square-Zahlungs-ID (verlinkt mit der Zahlung im Square Dashboard), dem Square-Status, der Kartenmarke und den letzten 4 Ziffern, den Beträgen Paid / order / refunded, der Umgebung und dem Standort, einem Link zum Square-Beleg, einem Badge Sandbox bei Sandbox-Zahlungen, dem Erstattungsverlauf und den Square notes der Bestellung. Kartennummern werden nie gespeichert.

Erstattungen

Geben Sie im Block Square den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Square. Bestätigen Sie die Frage Diesen Betrag über Square erstatten? Dies kann nicht rückgängig gemacht werden. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattungen erfolgen im Betrag und in der Währung, die Square abgebucht hat. Nach einer Betragsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht den Bestellbetrag. Die Erstattung wird an die Umgebung (Sandbox oder Produktion) und den Standort gesendet, an dem die Zahlung erfolgte, daher muss der Access Token dieses Modus gesetzt 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 Erstattungsverlauf und die Notizen aufgenommen. Lehnt Square sie ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite überweisen kein Geld über Square zurück. Square schließt Erstattungen auf eigener Seite ab: Eine Erstattung, die Square später ablehnt, wird nicht zurückgemeldet, und Erstattungen, die im Square Dashboard vorgenommen werden, erscheinen nicht in PrestaShop.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Square Gateway ist der erste Block unter Modules > Module Manager > VibeFox Square Gateway > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-square und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nach einer Änderung der Shop-Adresse oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel gilt für eine Domain: die Domain des Hauptshops, auch bei einem Multistore-Setup. Das Entfernen des Schlüssels aus dem Shop gibt seinen 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 This payment method is not available. Please choose another one. Die PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen bleiben unberührt: Bezahlte Bestellungen bleiben bezahlt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

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 Warenkorbwährung USD, CAD, AUD, JPY, GBP oder EUR ist und der Währung Ihres Square-Standorts entspricht. Die Einstellungsseite zeigt für jedes dieser Probleme eine Warnung. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

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.

Die Zahlungsart verschwand nach dem Speichern: Die Währung des Square-Standorts unterscheidet sich von der Warenkorbwährung. Geben Sie die Location ID eines Square-Standorts in Ihrer Shop-Währung ein und speichern Sie erneut: Die Zahlungsart wird nach einer erfolgreichen Prüfung wieder angezeigt.

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, und es wurde noch keine Zahlung gefunden. Prüfen Sie die Zahlungen dieses Standorts im Square Dashboard (Referenz = Warenkorb-ID). Versucht es der Kunde erneut, sucht das Modul zuerst nach der früheren Zahlung und legt die Bestellung damit an, statt erneut zu belasten.

Der Kunde sah Ihre Zahlung wurde empfangen, aber die Bestellung konnte nicht automatisch abgeschlossen werden: Die Karte wurde belastet, aber PrestaShop konnte die Bestellung nicht anlegen (zum Beispiel weil das Modul in diesem Moment deaktiviert war). Lesen Sie das Protokoll und legen Sie die Bestellung dann manuell an oder erstatten Sie die Zahlung im Square Dashboard.

Die Bestellung ist Square payment on hold: Lesen Sie die Notizen im Block Square (siehe Bestellstatus). Prüfen Sie die Zahlung 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 erfolgte im Sandbox- oder Live-Modus, und der Access Token dieses Modus ist nicht gesetzt. Geben Sie ihn ein und versuchen Sie es erneut.

Andere Fehler: Schalten Sie Debug log ein und sehen Sie im Feld Log auf der Modulseite nach.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Square Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Gateway-Einstellungen und die Protokolldateien entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Square-Zahlungen und -Erstattungen der Bestellungen sowie der Bestellstatus Square payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Square-Zahlungs-IDs und Transaktions-IDs.

Square ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Square verbunden noch von Square empfohlen.