VibeFox Ozow 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: südafrikanischer Rand (ZAR). Die Zahlungsart wird nur für Warenkörbe in ZAR angezeigt. Ozow rechnet in ganzen Cent ab, daher sollte die Währung 2 Nachkommastellen verwenden.

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

Erreichbare Website: Ihr Shop muss aus dem Internet erreichbar sein, ohne Passwortschutz und ohne Firewall, die Ozow blockiert, damit die Benachrichtigungen von Ozow ankommen. Die Benachrichtigung wird auch dann angenommen, wenn der Shop im Wartungsmodus ist.

VibeFox-Lizenzschlüssel: gekauft auf vibefox.net. 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 VibeFox Ozow Pay später in der Modulliste und klicken Sie auf Configure.

3. Fügen 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. Geben Sie Site Code und Private Key sowie vorzugsweise den API Key aus Ihrem Ozow-Händler-Dashboard ein.

5. Schalten Sie Enable/Disable ein und klicken Sie auf Save. Machen Sie eine Testzahlung mit eingeschaltetem Test mode und schalten Sie den Testmodus danach aus, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Ozow payment und Ozow payment on hold. PrestaShop stellt für alle Währungen, Länder und Kundengruppen ein neues Zahlungsmodul bereit. Sie können dies unter Payment > Preferences einschränken; dort muss ZAR für das Modul erlaubt sein. Ein später aktiviertes Land muss dort ebenfalls für das Modul angehakt werden.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Ozow Pay > Configure. Jeder Abschnitt mit einer Schaltfläche Save speichert die gesamte Seite. Oberhalb der Felder warnt Sie die Seite, wenn Site Code oder Private Key fehlen (Ozow wird dann an der Kasse ausgeblendet), wenn die Standardwährung des Shops nicht ZAR ist, wenn die Währung mehr als 2 Nachkommastellen hat (stellen Sie sie unter International > Localization > Currencies auf 2 ein), und zeigt Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. an, solange der Testmodus eingeschaltet ist.

Ozow

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

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. 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 (nur wenn die Beschreibung nicht leer ist).

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 unter 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 ist die Zahlungsart ausgeblendet und keine Antwort von Ozow wird 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 diesen Warenkorb, mit demselben Betrag, derselben Währung und demselben Site Code.

Gespeicherte Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved secrets: Setzen Sie den Haken bei Private Key oder API Key und speichern Sie, um einen gespeicherten Schlüssel zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

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 Bestellnachricht; versenden Sie sie nicht. Schalten Sie den Testmodus aus, um echte Zahlungen anzunehmen. Eine Testzahlung bezahlt im Live-Modus nie eine Bestellung. Standard: on.

Zahlungsbenachrichtigungen

Die URLs für Benachrichtigung, Erfolg, Abbruch und Fehler werden bei jeder Zahlung an Ozow gesendet, daher muss im Ozow-Dashboard nichts konfiguriert werden, außer Ihre Ozow-Site ist auf feste URLs eingestellt. Der Abschnitt zeigt alle vier URLs: Notification URL, Success URL, Cancel URL und Error URL. Es sind Modul-Links Ihres Shops (Controller notify und return). Wenn Ihre Ozow-Site feste URLs verwendet, kopieren Sie diese genau so, wie die Einstellungen sie anzeigen.

Erweitert

Debug log: protokolliert Zahlungsanfragen und Antworten von Ozow in logs/ozow_p_debug.log.php im Modulordner (nicht aus dem Web lesbar). Fehler und Warnungen werden immer protokolliert. Schlüssel, Hashes, Tokens und Kundendaten werden nie protokolliert. Standard: off.

Log: zeigt die aktuelle Größe und das Ende des Protokolls mit einer Schaltfläche Clear log.

Delete data on uninstall: entfernt beim Deinstallieren die Einstellungen und Protokolle dieses Moduls (Ozow-Daten, die in Bestellungen gespeichert sind, bleiben erhalten). Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Instant EFT (Ozow)) und bestätigt die Bestellung. Das Modul leitet den Kunden mit einer signierten Anfrage über den Warenkorb-Gesamtbetrag in ZAR zur gehosteten Ozow-Zahlungsseite weiter. Der Verwendungszweck auf dem Kontoauszug ist Cart und die Warenkorbnummer (bis zu 20 lateinische Buchstaben, Ziffern, Leerzeichen und Bindestriche). Der Name des Kunden wird an Ozow übergeben. Zu diesem Zeitpunkt existiert noch keine Bestellung. Auf der Ozow-Seite wählt der Kunde eine südafrikanische Bank und bestätigt die Zahlung in der Banking-App.

Danach benachrichtigt Ozow den Shop und sendet den Kunden zurück. Beide enthalten dieselbe signierte Antwort und werden auf dieselbe Weise verarbeitet, sodass die Bestellung auch dann angelegt wird, wenn eines davon verloren geht. Die Bestellung wird erst als bezahlt markiert, nachdem Ozow sie bestätigt hat: Der Hash muss mit Ihrem Private Key prüfbar sein, der Site Code muss Ihrem entsprechen, die Antwort muss zu diesem Zahlungsversuch des Warenkorbs gehören, und Betrag und Währung müssen mit dem Warenkorb übereinstimmen. Mit einem API Key wird die Zahlung zusätzlich über die GetTransaction API geprüft.

Nach einer erfolgreichen Zahlung sieht der Kunde die übliche Bestellbestätigungsseite. Wenn Ozow oder die Bank die Zahlung noch prüft, lautet der Text auf der 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. Wenn die Bestellung auf Hold ist, lautet er Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. Schlägt eine geprüfte Zahlung später fehl oder wird die unbezahlte Bestellung storniert, lautet er Your Ozow payment was not completed. Please contact us about this order. Hat Ozow die Zahlung noch nicht bestätigt, wenn der Kunde zurückkehrt, zeigt eine Seite den Wartetext mit den Schaltflächen Check again und Back to checkout.

Bricht der Kunde auf der Ozow-Seite ab oder schlägt die Zahlung fehl, wird keine Bestellung angelegt. Der Kunde kehrt mit demselben Warenkorb zur Kasse zurück und sieht 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.

Ist der Warenkorb nicht in ZAR, sieht der Kunde Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

Das Modul nimmt nur einmalige Zahlungen in ZAR an. Es bietet keine Erstattungen aus PrestaShop, keine Abonnements, keine gespeicherten Bankkonten oder Tokenisierung und keine Zahlungslinks, die aus dem Back Office verschickt werden.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: der Kunde wurde zu Ozow geschickt und hat nicht bezahlt, abgebrochen, oder Ozow hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted: die Zahlung wurde bestätigt. Die Bestellnachricht zeigt den Betrag und die Ozow-Transaktionsnummer sowie, ob die Zahlung über die GetTransaction API bestätigt wurde. Die Transaktionsnummer der Bestellzahlung ist die Ozow TransactionId. Eine Testzahlung erhält die Nachricht TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: Ozow oder die Bank prüft die Zahlung. Die Bestellung wird aktualisiert, wenn Ozow den endgültigen Status sendet.

Ozow payment on hold: die Bestellnachricht nennt den Grund: Der bezahlte Betrag oder die Währung weicht vom Warenkorb ab; eine Zahlung kam für eine bereits stornierte Bestellung; 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.

Zahlungsfehler: eine Zahlung, die geprüft wurde, wurde abgebrochen, aufgegeben oder ist fehlgeschlagen. Eine spätere erfolgreiche Antwort von Ozow dafür markiert die Bestellung trotzdem als bezahlt.

Eine bereits bezahlte Bestellung wird nie zurückgesetzt, und eine stornierte oder erstattete Bestellung wird nie wieder geöffnet. Kommt eine zweite Zahlung für eine bereits bezahlte Bestellung, fordert eine Meldung Sie auf, das Duplikat in Ihrem Ozow-Dashboard zu erstatten. Ist eine Bestellung aus einem anderen Grund auf Hold, zum Beispiel von Ihnen gesetzt, fügt eine spätere Zahlung nur eine Nachricht hinzu, und Sie setzen die Bestellung selbst auf Payment accepted.

Ozow-Zahlungsblock

Die Bestellseite zeigt einen Block Ozow payment mit der Transaktionsreferenz und dem Versuch, der Ozow-Transaktionsnummer, dem Status, dem angefragten Betrag, dem von Ozow gemeldeten Betrag, der Ozow-Nachricht und einer Markierung TEST MODE bei Testzahlungen.

Erstattungen

Erstattungen aus PrestaShop werden nicht unterstützt. Erstatten Sie die Zahlung in Ihrem Ozow-Händler-Dashboard und tragen Sie die Erstattung danach manuell in PrestaShop ein.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Ozow Pay ist der erste Block auf Modules > Module Manager > VibeFox Ozow Pay > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-ozow 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. Nachdem sich die Shop-Adresse geändert hat oder Sie einen Domain-Platz in Ihrem Konto 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 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. Der 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. Ein Hinweis erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt.

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

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 Warenkorbwährung ZAR ist. Prüfen Sie unter Payment > Preferences, ob das Modul für ZAR, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt.

Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: die Benachrichtigung von Ozow hat den Shop nicht erreicht und der Kunde ist nicht zurückgekehrt. Prüfen Sie, ob Ihr Shop aus dem Internet erreichbar ist (kein Passwortschutz und keine Firewall, die Ozow blockiert). Ist Ihre Ozow-Site auf feste URLs eingestellt, prüfen Sie, ob sie genau den Adressen unter Payment notifications entsprechen. Schalten Sie Debug log ein und lesen Sie das Protokoll auf der Seite Configure.

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. Es wird nichts geändert.

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 Zahlung, die in diesem Shop gestartet wurde. Es wird nichts geändert.

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

Die Benachrichtigung antwortet Payment not confirmed yet: die Antwort konnte noch nicht angewendet werden. Mit einem API Key konnte die GetTransaction API die Zahlung nicht bestätigen (die Bestellung ist auf Hold, und die nächste Benachrichtigung schließt sie ab; bleibt sie auf Hold, prüfen Sie den API Key und die Zahlung in Ihrem Ozow-Dashboard). Diese Antwort kommt auch, wenn die Rückkehr des Kunden für denselben Warenkorb im selben Moment verarbeitet wurde oder wenn die Bestellung nicht angelegt werden konnte; siehe Protokoll.

Eine Testzahlung hat die Bestellung nicht bezahlt: das Modul ist im Live-Modus. Testzahlungen bezahlen im Live-Modus nie eine Bestellung; die Bestellnachricht oder das Protokoll zeigt das an.

Die Bestellung steht nach der Zahlung auf Ozow payment on hold: lesen Sie die Bestellnachricht und prüfen Sie die Zahlung in Ihrem Ozow-Dashboard. Setzen Sie die Bestellung dann auf Payment accepted oder erstatten Sie die Zahlung in Ozow.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Ozow Pay und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Modul-Einstellungen und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Ozow-Zahlungsdatensätze und die Bestellstatus Awaiting Ozow payment und Ozow payment on hold bleiben immer erhalten, sodass späte Benachrichtigungen zu alten Bestellungen auch nach einer Neuinstallation erkannt werden. Bestehende Bestellungen behalten ihre Zahlungsnachrichten und Transaktionsnummern.

Ozow ist eine Marke des jeweiligen Rechteinhabers. Dieses Modul ist nicht mit Ozow verbunden und wird nicht von Ozow unterstützt.