VibeFox Ozow for WooCommerce — Hilfe

Anforderungen

WordPress: 6.2 oder neuer.

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

PHP: 8.0 oder neuer.

Währung: Südafrikanischer Rand (ZAR). Die Zahlungsart wird bei anderen Währungen ausgeblendet. Ozow berechnet ganze Cent, daher sollte WooCommerce 2 Dezimalstellen verwenden.

Ozow-Konto: ein Ozow-Händlerkonto mit Site Code und Private Key Ihrer Ozow-Site, zu finden im Ozow-Händler-Dashboard. Der API Key ist optional, wird aber empfohlen. Ozow verwendet für Test- und Live-Zahlungen denselben Site Code und dieselben Schlüssel.

Erreichbare Website: Ihre Website muss aus dem Internet erreichbar sein, ohne Wartungsmodus, Passwortschutz oder Firewall, die Ozow blockiert, damit die Benachrichtigungen von Ozow ankommen.

VibeFox-Lizenzschlüssel: gekauft auf vibefox.net. Ein Schlüssel funktioniert auf einer 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. Sie können den Ordner wcp_ozow_pay auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Ozow > Manage, oder klicken Sie auf der Seite Plugins unter dem Namen des Plugins auf Settings.

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

5. Geben Sie Site Code und Private Key sowie möglichst den API Key aus Ihrem Ozow-Händler-Dashboard ein.

6. Aktivieren Sie Enable/Disable. Machen Sie eine Testzahlung mit eingeschaltetem Test mode und schalten Sie den Testmodus danach aus, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Ozow. Oberhalb der Felder warnt die Seite, wenn Site Code oder Private Key fehlen (Ozow wird dann an der Kasse ausgeblendet), wenn die Shop-Währung nicht ZAR ist und wenn WooCommerce mehr als 2 Dezimalstellen verwendet. Solange der Testmodus eingeschaltet ist, zeigt sie außerdem Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. In der Liste der Zahlungsarten ist Ozow als einrichtungsbedürftig markiert, bis Site Code und Private Key eingetragen sind.

Allgemein

Enable/Disable: Enable Ozow payments schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Instant EFT (Ozow).

Description: der Text unter der Zahlungsart an der Kasse. Standard: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. Im Testmodus wird darunter die Zeile TEST MODE: no money will be charged. ergänzt.

Ozow-Zugangsdaten

Kopieren Sie Site Code, Private Key und API Key aus Ihrem Ozow-Händler-Dashboard (Merchant details / Sites). Der Abschnitt verlinkt auf die Ozow-Integrationsdokumentation auf hub.ozow.com.

Site Code: der Site Code der Ozow-Site, die die Zahlungen erhält. Antworten für einen anderen Site Code werden abgelehnt.

Private Key: signiert jede Zahlungsanfrage und prüft jede Antwort von Ozow. Halten Sie ihn geheim. Ohne ihn wird die Zahlungsart ausgeblendet und keine Antwort von Ozow akzeptiert.

API Key (recommended): optional. Mit einem API Key wird jede erfolgreiche Zahlung zusätzlich über die Ozow GetTransaction API bestätigt, bevor die Bestellung als bezahlt markiert wird. Die API muss die Zahlung als abgeschlossen melden, für diese Bestellung, mit demselben Betrag, derselben Währung und demselben Site Code.

Test mode: Enable Ozow test mode. Ozow verwendet für Tests denselben Site Code und dieselben Schlüssel: Zahlungen werden mit IsTest=true angelegt und es wird kein Geld bewegt. Bestellungen, die im Testmodus bezahlt wurden, erhalten eine Bestellnotiz; versenden Sie sie nicht. Schalten Sie den Testmodus aus, um echte Zahlungen anzunehmen. Eine Testzahlung bezahlt im Live-Modus nie eine Bestellung. Standard: an.

Zahlungsbenachrichtigungen

Die URLs für Benachrichtigung, Erfolg, Abbruch und Fehler werden bei jeder Zahlung an Ozow übermittelt. Im Ozow-Dashboard muss daher nichts eingerichtet werden, es sei denn, Ihre Ozow-Site ist auf feste URLs eingestellt. Der Abschnitt zeigt die Benachrichtigungs-URL. Sie sieht so aus: https://your-site/wc-api/ozow_pay/?ozow_notify=1. Wenn Ihre Ozow-Site feste URLs verwendet, kopieren Sie sie genau so, wie die Einstellungen sie anzeigen.

Erweitert

Debug log: Log payment requests and Ozow responses schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_ozow_pay. Fehler und Warnungen werden immer protokolliert. Schlüssel, Hashes und Kundendaten werden nie protokolliert. Standard: aus.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept). Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Instant EFT (Ozow)) und gibt die Bestellung auf. Das Plugin leitet den Kunden mit einer signierten Anfrage über den Bestellbetrag in ZAR auf die gehostete Ozow-Zahlungsseite weiter. Die Referenz im Kontoauszug ist Order und die Bestellnummer (bis zu 20 lateinische Buchstaben, Ziffern, Leerzeichen und Bindestriche). Der Name des Kunden wird an Ozow übergeben. Auf der Ozow-Seite wählt der Kunde eine südafrikanische Bank und bestätigt die Zahlung in der Banking-App.

Anschließend benachrichtigt Ozow den Shop und schickt den Kunden zurück. Beide enthalten dieselbe signierte Antwort und werden auf dieselbe Weise verarbeitet, sodass die Bestellung auch dann aktualisiert wird, wenn eine der beiden verloren geht. Die Bestellung wird erst als bezahlt markiert, nachdem Ozow die Zahlung bestätigt hat: Der Hash muss mit Ihrem Private Key geprüft werden können, der Site Code muss Ihrer sein, die Antwort muss den Schlüssel dieser Bestellung enthalten, und Betrag und Währung müssen mit der Bestellung übereinstimmen. Mit einem API Key wird die Zahlung außerdem über die GetTransaction API geprüft.

Nach einer erfolgreichen Zahlung landet der Kunde auf der Seite Bestellung eingegangen. Hat Ozow die Zahlung noch nicht bestätigt, zeigt die Seite We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Ist die Bestellung auf Halten gesetzt, steht dort Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed.

Bricht der Kunde auf der Ozow-Seite ab oder schlägt die Zahlung fehl, wird die Bestellung auf Fehlgeschlagen gesetzt und der Kunde kehrt zur Seite Pay for order zurück, mit The Ozow payment was cancelled. You can try again or choose another payment method. oder The Ozow payment was not completed. You can try again or choose another payment method. Der Kunde kann dieselbe Bestellung erneut bezahlen.

Die Zahlungsart funktioniert an der klassischen Kasse, im Checkout-Block und auf der Seite Pay for order (nur für Bestellungen in ZAR). Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin nimmt nur einmalige Zahlungen in ZAR an. Es bietet keine Erstattungen aus WooCommerce, keine Abonnements, keine gespeicherten Bankkonten oder Tokenisierung und keine Zahlungslinks, die aus dem Admin-Bereich verschickt werden.

Bestellungen

Bestellstatus

Pending payment: Der Kunde wurde zu Ozow weitergeleitet und hat noch nicht bezahlt, oder Ozow hat die Zahlung noch nicht bestätigt.

Processing: Die Zahlung wurde bestätigt. Dies ist der übliche WooCommerce-Status nach der Zahlung; Bestellungen mit nur virtuellen, herunterladbaren Produkten werden auf Completed gesetzt. Die Bestellnotiz zeigt den Betrag und die Ozow-Transaktions-ID sowie, ob die Zahlung über die GetTransaction API bestätigt wurde. Die Transaktions-ID der Bestellung ist die Ozow TransactionId. Eine Testzahlung erhält die Notiz TEST MODE — no money was received, do not ship this order.

On hold: Die Bestellnotiz nennt den Grund. Ozow oder die Bank prüft die Zahlung (die Bestellung wird aktualisiert, sobald Ozow den endgültigen Status sendet); der bezahlte Betrag oder die Währung weicht von der Bestellung ab; eine Zahlung ist für eine bereits stornierte Bestellung eingegangen; oder, mit einem API Key, konnte die GetTransaction API die Zahlung noch nicht bestätigen oder widerspricht ihr. Prüfen Sie die Zahlung in Ihrem Ozow-Dashboard und ändern Sie den Bestellstatus. Konnte die API nicht antworten, schließt die nächste Benachrichtigung von Ozow die Bestellung ab.

Failed: Der Kunde hat die Zahlung abgebrochen, sie wurde verlassen oder Ozow hat einen Fehler gemeldet. Der Kunde kann über die Bestellung erneut bezahlen.

Eine bereits bezahlte Bestellung wird nie zurückgesetzt, und eine stornierte oder erstattete Bestellung wird nie wieder geöffnet. Trifft für eine bereits bezahlte Bestellung eine zweite Zahlung ein, weist eine Notiz Sie an, das Duplikat im Ozow-Dashboard zu erstatten. Ist die Bestellung aus einem anderen Grund auf Halten gesetzt, etwa durch Sie selbst, fügt eine spätere Zahlung nur eine Notiz hinzu, und Sie setzen die Bestellung selbst auf Processing.

Erstattungen

Erstattungen aus WooCommerce werden nicht unterstützt. Erstatten Sie die Zahlung im Ozow-Händler-Dashboard und erfassen Sie die Erstattung in WooCommerce manuell.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Ozow. Fügen Sie den Schlüssel bei License key ein und klicken Sie auf Activate. Der Block zeigt den Status, etwa 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 funktioniert auf einer 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 Ozow Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt.

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

Fehlerbehebung

Ozow erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, Site Code und Private Key ausgefüllt sind und die Shop- oder Bestellwährung ZAR ist. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt.

Die Zahlung ist erfolgt, die Bestellung bleibt aber auf Pending payment: Die Benachrichtigung von Ozow hat den Shop nicht erreicht und der Kunde ist nicht zurückgekehrt. Prüfen Sie, ob Ihre Website aus dem Internet erreichbar ist (kein Wartungsmodus, kein Passwortschutz und keine Firewall, die Ozow blockiert). Ist Ihre Ozow-Site auf feste URLs eingestellt, prüfen Sie, ob die Benachrichtigungs-URL genau der in den Einstellungen angezeigten entspricht. Aktivieren Sie Debug log und sehen Sie unter WooCommerce > Status > Logs mit der Quelle wcp_ozow_pay nach.

Die Benachrichtigung antwortet Invalid hash: Der Private Key in den Einstellungen gehört nicht zu der Ozow-Site, die die Antwort gesendet hat. Kopieren Sie ihn erneut aus dem Ozow-Händler-Dashboard.

Die Benachrichtigung antwortet Unknown site: Die Antwort stammt von einer anderen Ozow-Site. Prüfen Sie den Site Code.

Die Benachrichtigung antwortet Order mismatch oder Order not found: Die Antwort gehört zu keiner Bestellung dieses Shops. Es wird nichts verändert.

Die Benachrichtigung antwortet Gateway not configured: Site Code oder Private Key fehlt. Tragen Sie sie ein; Ozow kann es erneut versuchen.

Die Benachrichtigung antwortet Order busy: Eine andere Antwort von Ozow zur selben Bestellung wurde im selben Moment verarbeitet. Die Antwort wird nicht angewendet; die nächste Benachrichtigung oder die Rückkehr des Kunden wendet sie an.

Die Benachrichtigung antwortet Payment not confirmed yet: Mit einem API Key konnte die GetTransaction API die Zahlung nicht bestätigen. Die Bestellung ist auf Halten gesetzt, und die nächste Benachrichtigung schließt sie ab. Bleibt sie auf Halten, prüfen Sie den API Key und die Zahlung in Ihrem Ozow-Dashboard.

Der Kunde sieht Ozow accepts payments in South African rand (ZAR) only: Die Bestellung ist in einer anderen Währung. Dafür kann Ozow nicht verwendet werden.

Eine Testzahlung hat die Bestellung nicht bezahlt: Das Gateway ist im Live-Modus. Testzahlungen bezahlen im Live-Modus nie eine Bestellung; eine Notiz an der Bestellung weist darauf hin.

Bestellung ist nach der Zahlung On hold: Lesen Sie die Bestellnotiz und prüfen Sie die Zahlung in Ihrem Ozow-Dashboard. Setzen Sie die Bestellung dann auf Processing oder erstatten Sie die Zahlung in Ozow.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel etwa 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, die übrigen Optionen des Plugins und seine Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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