VibeFox Yoco for OpenCart — Hilfe

Anforderungen

OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).

PHP: 8.0 oder neuer.

Shop-Währung: Die südafrikanische Rand-Währung (ZAR) muss unter System > Localisation > Currencies als aktive Währung eingerichtet sein. Yoco akzeptiert nur ZAR. Zahlt der Kunde in einer anderen Währung, wird die Zahlungsart an der Kasse ausgeblendet. Der Bestellbetrag muss mindestens R2.00 betragen.

Yoco-Konto: ein Yoco-Konto mit Online-Zahlungen. Sie benötigen dessen geheime Schlüssel, die Sie im Yoco Business Portal unter Selling Online > Payment Gateway finden. Eingegeben werden nur die geheimen Schlüssel. Der Webhook wird von der Erweiterung registriert, und sein Signaturgeheimnis wird für Sie eingetragen.

Öffentliche Website: Yoco sendet Webhooks an Ihren Shop, daher muss er aus dem Internet erreichbar sein.

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

Installation

Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das OpenCart-3-Paket wcp_yoco_pay-oc3-(version).ocmod.zip und das OpenCart-4-Paket wcp_yoco_pay.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen derselbe.

OpenCart 3

1. Gehen Sie im Administrationsbereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_yoco_pay-oc3-(version).ocmod.zip. Die Erweiterung enthält keine OCMOD-Modifikationen, daher muss Extensions > Modifications nicht aktualisiert werden. Statt des Installers können Sie auch den Inhalt des Ordners upload dieses Pakets in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox Yoco Pay Gateway und klicken Sie auf Install (die grüne +-Schaltfläche). Ihr Administrator-Benutzer benötigt das Recht, die Liste der Zahlungserweiterungen zu ändern.

3. Klicken Sie auf Edit (die Stift-Schaltfläche), um die Einstellungsseite zu öffnen. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate (siehe License key).

4. Fügen Sie den geheimen Testschlüssel (sk_test_...) ein und, wenn Sie so weit sind, den geheimen Live-Schlüssel (sk_live_...). Klicken Sie auf Save. Der Webhook wird für jeden Modus registriert, für den ein Schlüssel vorhanden ist.

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Führen Sie bei eingeschaltetem Test mode eine Testzahlung mit einer Yoco-Testkarte durch und schalten Sie danach Test mode aus, um echte Zahlungen anzunehmen.

OpenCart 4

1. Gehen Sie im Administrationsbereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_yoco_pay.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Code der Erweiterung dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.

2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox Yoco Pay Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel und die Yoco-Schlüssel ein wie in den Schritten 3 bis 5 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Webhook-URL ist anders (siehe Webhook); sie wird beim Speichern auf die gleiche Weise bei Yoco registriert.

Eine Neuinstallation startet mit ausgeschalteter Zahlungsart und eingeschaltetem Testmodus.

Konfiguration

Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox Yoco Pay Gateway > Edit. Die Abschnitte sind links aufgeführt; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Ohne das Recht, die Erweiterung zu ändern, zeigt die Seite die Einstellungen, kann sie aber nicht speichern.

Oberhalb der Einstellungen zeigt die Seite den aktiven Modus (Test mode: the test secret key is used, no real money is charged. oder Live mode: real payments are accepted.). Sie warnt Sie, wenn die Standardwährung des Shops nicht ZAR ist (Yoco wird dann nur angeboten, wenn der Kunde in ZAR zahlt, oder gar nicht, wenn keine ZAR-Währung aktiviert ist), und wenn dem aktuellen Modus ein geheimer Schlüssel fehlt, zum Beispiel Enter the test secret key to offer Yoco at checkout (test mode).

Beim Speichern darf Title höchstens 128 Zeichen haben, Sort Order muss eine ganze Zahl sein (negative Zahlen sind erlaubt), Total muss eine Zahl sein, 0 oder größer, und die Geozone sowie die Bestellstatus müssen existieren. Andernfalls wird nichts gespeichert und die Seite nennt das Feld. Danach prüft die Erweiterung die Schlüssel und Webhook-Geheimnisse und registriert die Webhooks. Hinweise dazu erscheinen über den Einstellungen.

Yoco

Enable/Disable: Enable Yoco 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: Card or Instant EFT (Yoco). Bis zu 128 Zeichen; ist das Feld leer, sehen Kunden Card or Instant EFT (Yoco).

Description: der Text, der dem Kunden im Schritt Confirm Order über der Bestätigungsschaltfläche angezeigt wird. Standard: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Sort Order: die Position von Yoco unter den Zahlungsarten an der Kasse. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein.

Geo Zone: Yoco nur für Zahlungsadressen in der gewählten Geozone anbieten. Standard: All zones. Geozonen werden unter System > Localisation > Geo Zones eingerichtet.

Total: der Kassenbetrag in der Standardwährung des Shops, den eine Bestellung erreichen muss, bevor Yoco angeboten wird. Lassen Sie das Feld leer, um Yoco bei jedem Betrag anzubieten. Yoco selbst benötigt immer mindestens R2.00.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus dem Yoco Business Portal unter Selling Online > Payment Gateway (dort gibt es einen Link zum Abschnitt). Yoco hat eine API für beide Modi: Der Schlüssel entscheidet, ob eine Zahlung eine Testzahlung oder eine echte Zahlung ist. Der Testmodus verwendet nur den Testschlüssel, der Livemodus nur den Live-Schlüssel.

Test mode: verwendet den geheimen Testschlüssel. Es wird kein echtes Geld belastet; bezahlen Sie mit Yoco-Testkarten. Standard: on. Schalten Sie es aus, um echte Zahlungen anzunehmen. Solange es eingeschaltet ist, sehen Kunden im Schritt Confirm Order Test mode — use a Yoco test card; no real money is charged.

Test secret key: der geheime Schlüssel des Testmodus. Er beginnt mit sk_test_.

Live secret key: der geheime Schlüssel des Livemodus. Er beginnt mit sk_live_.

Ein Schlüssel, der nicht mit dem erwarteten Präfix beginnt, wird nicht gespeichert: Die Seite zeigt einen Fehler, zum Beispiel Yoco: the test secret key must start with sk_test_ — the previous value was kept. Die übrigen Einstellungen werden gespeichert. Meldet Yoco bei der Webhook-Registrierung, dass ein Schlüssel zum anderen Modus gehört, zeigt die Seite dies an.

Gespeicherte Schlüssel und Geheimnisse werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie einen neuen Wert nur ein, wenn Sie ihn ändern möchten. Um einen gespeicherten Wert zu entfernen, setzen Sie unter dem Feld den Haken bei Clear the saved value und klicken Sie auf Save.

Webhooks

Yoco meldet Zahlungen und Erstattungen an die URL, die in diesem Abschnitt unter Webhook URL angezeigt wird. Auf OpenCart 3 sieht sie etwa so aus: https://your-store/index.php?route=extension/payment/wcp_yoco_pay/webhook, auf OpenCart 4 so: https://your-store/index.php?route=extension/wcp_yoco_pay/payment/wcp_yoco_pay.webhook. Sie wird aus der Shop-Adresse Ihrer OpenCart-Installation gebildet. Den Webhook müssen Sie nicht im Yoco-Portal anlegen. Beim Speichern der Einstellungen registriert die Erweiterung die URL bei Yoco für jeden Modus, der einen geheimen Schlüssel, aber kein Webhook-Geheimnis hat, und speichert das Signaturgeheimnis im Feld dieses Modus. Sie registriert die URL erneut, wenn sich der geheime Schlüssel dieses Modus oder die Webhook-URL ändert. Ändert sich die URL, wird die alte Registrierung entfernt.

Für jeden Modus (Test und Live) zeigt der Abschnitt den Status des Webhooks:

Die Erweiterung verarbeitet diese Ereignisse (sie sind in diesem Abschnitt ebenfalls aufgeführt):

Webhooks ohne gültige Signatur werden abgewiesen. Ein Ereignis muss mit dem Geheimnis des Modus signiert sein, in dem die Zahlung erfolgte, sodass ein Testgeheimnis nie eine Live-Zahlung bestätigt.

Test webhook secret: wird beim Registrieren des Webhooks automatisch eingetragen. Fügen Sie ein Geheimnis (whsec_...) nur ein, wenn Sie die Webhook-URL selbst registriert haben.

Live webhook secret: wird beim Registrieren des Webhooks automatisch eingetragen. Leeren Sie es und speichern Sie, um den Webhook erneut zu registrieren.

Ein Webhook-Geheimnis muss die Form whsec_ mit anschließendem Base64-Text haben. Jeder andere Wert wird nicht gespeichert, und der vorherige Wert bleibt erhalten. Ein Webhook-Geheimnis zu leeren und zu speichern, registriert den Webhook erneut.

Bestellungen

OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (eine fehlende Bestellung). Die Bestellung erhält einen Status erst, nachdem Yoco die Zahlung über die API bestätigt hat. Jedes der folgenden Felder listet Ihre OpenCart-Bestellstatus auf.

Paid Order Status: der Status nach einer bestätigten Zahlung. Standard: Processing.

On Hold Status: eine Zahlung, deren Betrag oder Währung nicht dem Bestellbetrag entspricht, setzt die Bestellung mit einer Notiz in diesen Status. Eine spätere Zahlung mit dem richtigen Betrag gleicht sie aus. Standard: Pending, weil OpenCart keinen Status On hold hat. Sie können unter System > Localisation > Order Statuses einen eigenen Status anlegen und hier auswählen.

Refunded Status: wird gesetzt, wenn die Erstattungen den bezahlten Betrag erreichen. Standard: Refunded.

Erweitert

Debug log: schreibt Yoco-Anfragen und Webhooks in yoco_p_debug.log.php im Protokollordner von OpenCart (storage/logs, unter OpenCart 4 system/storage/logs). Die Datei kann nicht über das Web geöffnet werden und wird bei 5 MB nach yoco_p_debug.old.log.php verschoben. Fehler und Warnungen, etwa fehlgeschlagene Anfragen an Yoco und abgewiesene Webhooks, werden immer protokolliert. Schlüssel, Webhook-Geheimnisse und E-Mail-Adressen werden ausgeblendet. 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: wenn eingeschaltet, entfernt die Deinstallation der Erweiterung die Gateway-Einstellungen, das Protokoll und die Webhooks, die die Erweiterung bei Yoco registriert hat. Bestelldaten (Yoco-Checkout- und Zahlungs-IDs, Erstattungen) bleiben immer erhalten, weil sie für Erstattungen benötigt werden. Standard: off.

Import / Export

Export: Download JSON speichert die Einstellungen als JSON-Datei. Geheime Schlüssel und Webhook-Geheimnisse werden nicht exportiert.

Import: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Die gespeicherten Geheimnisse bleiben erhalten, und durch einen Import wird kein Webhook registriert.

Kasse

Die Zahlungsart wird angezeigt, wenn der Kunde in ZAR zahlt und der Bestellbetrag mindestens R2.00 beträgt. Im Schritt Payment Method wählt der Kunde sie aus (standardmäßig Card or Instant EFT (Yoco)). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung. OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. Auf OpenCart 4 wählt der Kunde die Zahlungsart mit der Schaltfläche Choose im Block der Zahlungsart im Fenster Payment method options und klickt unten auf der Kassenseite auf Confirm Order. Klickt der Kunde auf Confirm Order, erstellt die Erweiterung einen Yoco-Checkout für den Bestellbetrag in Cent und leitet den Kunden zur Yoco-Zahlungsseite weiter, wo er mit Karte oder Instant EFT zahlt.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird nur als bezahlt markiert, wenn Yoco die Zahlung bestätigt: Die Erweiterung fragt bei Yoco den Checkout ab, wenn der Kunde zurückkehrt, und erneut, wenn der signierte Webhook eintrifft. Danach erhält die Bestellung ihren Status auf die übliche OpenCart-Weise, mit den üblichen Bestell-E-Mails und der Bestandsaktualisierung, und der Kunde sieht die OpenCart-Erfolgsseite mit Your payment with Yoco has been received. Hat Yoco die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt, zeigt eine Seite Payment confirmation den Hinweis We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. mit den Schaltflächen Check again und Back to checkout; der Webhook setzt den Bestellstatus, sobald er eintrifft. Auf OpenCart 4 öffnet beim Zurückkehren des Kunden von der Yoco-Seite eine kurze Zwischenseite die Rückkehradresse Ihres Shops erneut, sodass Warenkorb und Kunden-Anmeldung erhalten bleiben.

Bricht der Kunde auf der Yoco-Seite ab, kehrt er an die Kasse zurück, mit The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. Schlägt die Zahlung fehl, lautet die Meldung The Yoco payment was not successful. Please try again or choose another payment method., und der Bestellung wird eine Notiz hinzugefügt. Der Warenkorb bleibt erhalten. Auf OpenCart 4 werden diese Meldungen über der Kasse angezeigt.

OpenCart 3 legt jedes Mal eine neue Bestellung an, wenn der Schritt Confirm Order angezeigt wird; OpenCart 4 aktualisiert die Bestellung der Kasse. Vor einer neuen Zahlung prüft die Erweiterung den Warenkorb: Ist eine andere Bestellung desselben Warenkorbs bereits bezahlt, gelangt der Kunde direkt zur Erfolgsseite. Unbezahlte Yoco-Checkouts dieser Bestellung und des Warenkorbs der letzten 24 Stunden werden zuerst bei Yoco geprüft; wurde einer inzwischen bezahlt, wird diese Zahlung bestätigt statt einer neuen. Ist der offene Checkout derselben Bestellung für denselben Betrag und Modus und vor weniger als 30 Minuten erstellt worden, erhält der Kunde erneut dieselbe Yoco-Seite. Andernfalls wird ein neuer Yoco-Checkout erstellt. Eine Änderung des Warenkorbs, auch eine neue Menge, gilt als neuer Warenkorb, der eine eigene Zahlung braucht.

OpenCart 4 hält die Bestellung in der Kasse bis zur Anzeige der Erfolgsseite, daher bezahlt der Kunde nach einer abgebrochenen oder fehlgeschlagenen Zahlung dieselbe Bestellung erneut. Wurde diese Bestellung inzwischen ohne Zahlung geschlossen (zum Beispiel haben Sie sie storniert), kehrt der Kunde mit Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. zur Kasse zurück, und der nächste Confirm Order bezahlt eine neue Bestellung.

Kann Yoco die Zahlung nicht starten, bleibt der Kunde im Schritt Confirm Order mit Yoco could not start the payment. Please try again in a moment or choose another payment method. über der Schaltfläche, und der Grund wird im Protokoll und in den Bestellnotizen festgehalten. Eine Bestellung unter R2.00 erhält Yoco requires an order total of at least R2.00.

Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist, weil OpenCart Anfragen von Zahlungserweiterungen durchlässt. Auf OpenCart 4 lässt eine Startaktion der Erweiterung den Webhook und die Rückkehr des Kunden durch.

Zahlungen werden auf der Yoco-Seite sofort belastet. Die Erweiterung bietet keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, kein Kartenformular im Shop und keine getrennte Autorisierung und Erfassung, und sie funktioniert nicht mit anderen Währungen als ZAR.

Bestellungen und Erstattungen

Bestellstatus

Kein Status (fehlende Bestellung): der Kunde wurde zu Yoco geschickt und hat nicht bezahlt, auf der Yoco-Seite abgebrochen, oder Yoco hat die Zahlung noch nicht bestätigt. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt. Auf OpenCart 4.1 kann eine solche Bestellung auch den Status Voided haben, den OpenCart setzt, wenn der Bestätigungsschritt erneut angezeigt wird; die Erweiterung zählt sie als Bestellung ohne Status.

Paid Order Status (Standard Processing): die Zahlung wurde bestätigt. Eine Notiz zeigt den Betrag, die Yoco-Zahlungs- und Checkout-IDs, den Modus und wie die Zahlung bestätigt wurde (Rückkehr des Kunden, Webhook oder eine Prüfung vor einem neuen Zahlungsversuch).

On Hold Status (Standard Pending): Yoco hat einen anderen Betrag oder eine andere Währung als den Bestellbetrag gemeldet, zum Beispiel weil der Warenkorb nach Zahlungsbeginn in einem anderen Tab geändert wurde. Die Notiz erklärt dies, und der Kunde sieht We received your payment and are reviewing it. We will contact you if anything else is needed. Prüfen Sie die Zahlung vor dem Versand. Zahlt der Kunde danach mit einem weiteren Versuch den richtigen Betrag, wechselt die Bestellung zu Paid Order Status.

Refunded Status (Standard Refunded): die Erstattungen haben den bezahlten Betrag erreicht.

Geht eine Zahlung für eine Bestellung mit einem anderen Status ein, etwa storniert oder erstattet, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, die Zahlung im Yoco-Portal zu erstatten oder die Bestellung manuell wiederherzustellen. Der Kunde sieht Your payment was received after the order had been cancelled. Please contact us — do not pay again.

Geht eine zweite Zahlung für eine bereits bezahlte Bestellung oder für eine andere Bestellung eines bereits bezahlten Warenkorbs ein, bleibt die Bestellung unverändert. Eine Notiz an der bezahlten Bestellung bittet Sie, sie im Yoco-Portal zu erstatten.

Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht. Sie beginnen mit dem Wort Yoco.

VibeFox Yoco Pay Gateway tab

Öffnen Sie unter Sales > Orders eine mit Yoco bezahlte Bestellung. Unten auf der Bestellseite, neben History und Additional, zeigt der Reiter VibeFox Yoco Pay Gateway die Checkout ID, die Payment ID, den Mode (mit der Bezeichnung Test bei Testzahlungen), den Status, die Beträge Paid / refunded, das Erstattungsformular, die Tabelle Yoco checkouts of this order, den Verlauf der Refunds und die Yoco notes der Bestellung. Der Reiter wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.

Erstattungen

Geben Sie im Reiter VibeFox Yoco Pay Gateway den Amount ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via Yoco. Bestätigen Sie die Frage Refund this amount through Yoco? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Erstattungen werden aus dem Betrag berechnet, den Yoco belastet hat; Sie können also höchstens erstatten, was der Kunde tatsächlich bezahlt hat, auch wenn die Bestellung später bearbeitet wurde. Die Erstattung wird im Modus gesendet, in dem die Zahlung erfolgte (Test oder Live), daher muss der geheime Schlüssel dieses Modus gesetzt sein. Eine nach einer verlorenen Antwort wiederholte Erstattung wird nicht doppelt ausgezahlt.

Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Yoco-Erstattungs-ID hinzugefügt. Erreichen die Erstattungen den bezahlten Betrag, erhält die Bestellung den Refunded Status, ohne dass der Kunde benachrichtigt wird und ohne dass Produkte in den Bestand zurückgebucht werden; eine Teilerstattung ändert den Status nicht. Lehnt Yoco die Erstattung ab, zeigt der Reiter Yoco refused the refund: mit dem Grund, und es wird keine Erstattung erfasst. Meldet Yoco die Erstattung als ausstehend, zeigt der Reiter dies an. Wiederholen Sie sie nicht: Sie wird erfasst, sobald Yoco sie per Webhook bestätigt. Erstattungen sind für Bestellungen verfügbar, die über einen Yoco-Checkout bezahlt wurden. Eine Bestellung im Status On Hold Status hat keine bezahlte Zahlung, die erstattet werden könnte; erstatten Sie sie im Yoco-Portal.

Produktrücksendungen unter Sales > Returns senden über Yoco kein Geld zurück.

Im Yoco-Portal vorgenommene Erstattungen kommen über den Webhook refund.succeeded an und werden im Erstattungsverlauf und in den Notizen erfasst. Erreichen sie den bezahlten Betrag, erhält die Bestellung den Refunded Status. Eine Erstattung, die größer ist als der noch erstattbare Betrag, wird nicht erfasst, und eine Notiz bittet Sie, die Bestellung zu prüfen. Eine fehlgeschlagene Erstattung fügt eine Notiz hinzu, dass das Geld nicht an den Kunden zurückgegeben wurde.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Yoco Pay Gateway ist der erste Block auf Extensions > Extensions > Payments > VibeFox Yoco Pay Gateway > Edit, 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: opencart-payment-yoco und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit dem Recht Modify für die Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Administrationsbereichs (Englisch und Russisch sind enthalten).

Wenn der Schlüssel nicht akzeptiert wird, zeigt 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 nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert für eine Domain: die Shop-Adresse aus der OpenCart-Konfiguration. 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 Yoco Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Admin-Benutzer, der im Administrationsbereich im selben Browser angemeldet ist, sieht die Zahlungsart im Shop weiterhin, markiert als (unlicensed — visible to admins only), damit Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Unter OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Zahlungsart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard des Administrationsbereichs. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Wenn eine Lizenz abläuft, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard des Administrationsbereichs oder die Seite Edit öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Beim Deinstallieren der Erweiterung werden immer der Lizenzschlüssel und der Lizenzstatus entfernt.

Fehlerbehebung

Yoco erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus einen geheimen Schlüssel hat: Test secret key im Testmodus, Live secret key im Livemodus. Der Kunde muss in ZAR zahlen, und der Bestellbetrag muss mindestens R2.00 betragen. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Shop-Währung nicht ZAR ist. Prüfen Sie außerdem, ob die Zahlungsadresse in der gewählten Geo Zone liegt und ob die Bestellung den in den Einstellungen festgelegten Total erreicht.

Die Zahlung ist erfolgt, aber die Bestellung bleibt ohne Status: der Webhook funktioniert nicht. Öffnen Sie den Abschnitt Webhooks der Einstellungen und prüfen Sie den Status des von Ihnen genutzten Modus. Ist er nicht registriert oder für eine andere URL registriert, speichern Sie die Einstellungen. Schlägt die Registrierung fehl, zeigt die Seite den Grund. Haben Sie das Geheimnis selbst eingegeben, prüfen Sie, ob es zum Webhook dieser URL und dieses Modus gehört. Die Bestellung erhält ihren Status auch, wenn der Kunde nach der Zahlung in den Shop zurückkehrt oder erneut zu zahlen versucht.

Webhook konnte nicht registriert werden: Zahlungen werden weiterhin bestätigt, wenn Kunden in den Shop zurückkehren. Beheben Sie den in der Meldung genannten Grund, zum Beispiel dass der Shop aus dem Internet erreichbar sein muss, und speichern Sie erneut. Sie können die URL auch selbst registrieren und das Signaturgeheimnis einfügen.

Webhooks werden abgewiesen: abgewiesene Webhooks werden im Protokoll festgehalten. webhook secret not configured bedeutet, dass kein Webhook-Geheimnis gesetzt ist. invalid signature bedeutet, dass das Geheimnis zu einer anderen Registrierung oder einem anderen Modus gehört. timestamp outside the tolerance bedeutet, dass die Serveruhr falsch geht: Signaturen werden nur innerhalb von 5 Minuten zur Serverzeit akzeptiert. checkout not completed yet — retry und could not confirm the checkout with Yoco — retry sind vorübergehend; Yoco sendet den Webhook erneut.

Die Webhook-URL zeigt im Browser nur POST: das ist normal. Die URL akzeptiert nur Anfragen von Yoco.

Der Fehler beim Speichern The secret key must start with sk_test_ / sk_live_: ein Schlüssel wurde in das falsche Feld eingefügt. Der Testschlüssel beginnt mit sk_test_, der Live-Schlüssel mit sk_live_. Der vorherige Wert wurde beibehalten.

Der Kunde sieht nach Confirm Order einen Fehler: sehen Sie im Feld Log der Erweiterungsseite nach. Yoco is not available at the moment. Please choose another payment method. bedeutet, dass dem aktuellen Modus ein geheimer Schlüssel fehlt.

Dem Kunden wird mitgeteilt, dass eine Zahlung geprüft werden muss: ein Versuch wurde mit einem anderen Betrag oder nach der Stornierung der Bestellung bezahlt. Lesen Sie die Notizen im Reiter VibeFox Yoco Pay Gateway und bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung im Yoco-Portal.

Erstattung schlägt mit einer Meldung zum Modus fehl: die Zahlung erfolgte im Test- oder Livemodus, und der geheime Schlüssel dieses Modus ist nicht gesetzt. Geben Sie ihn ein und versuchen Sie es erneut.

Erstattung schlägt mit No answer from Yoco fehl: in OpenCart wurde nichts erfasst. Hat Yoco die Erstattung doch verarbeitet, wiederholen Sie dieselbe Erstattung: Sie wird nicht doppelt erstattet.

Für Entwickler: Bevor der Yoco-Checkout erstellt wird, löst die Erweiterung das OpenCart-Ereignis yoco_p_checkout_payload mit den Anfragedaten und der Bestellung aus, damit eine andere Erweiterung die Anfrage ergänzen kann.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox Yoco Pay Gateway auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart entfernt immer die eigenen Einstellungen der Erweiterung: Enable/Disable, Sort Order, Geo Zone, Total und die Bestellstatus des Abschnitts Orders, die bei einer Neuinstallation auf ihre Standardwerte zurückgesetzt werden. Auch das OpenCart-Ereignis der Erweiterung wird entfernt (auf OpenCart 4 auch seine Ereignisse und seine Startaktion, die im Wartungsmodus den Webhook und die Rückkehr des Kunden durchlässt). Ist Delete data eingeschaltet, werden die übrigen Gateway-Einstellungen (Titel, Beschreibung, Testmodus, Schlüssel, Webhook-Geheimnisse, Protokollierung), das Protokoll und die Webhooks, die die Erweiterung bei Yoco registriert hat, entfernt. Ist es ausgeschaltet, bleiben sie für eine spätere Neuinstallation erhalten. Yoco-Checkouts und -Erstattungen werden immer aufbewahrt, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen.

Auf OpenCart 4 entfernen Sie die Dateien der Erweiterung ebenfalls, indem Sie nach der Deinstallation zu Extensions > Installer gehen, neben VibeFox Yoco Pay Gateway in der Liste der installierten Erweiterungen auf Uninstall (die orangefarbene −-Schaltfläche) klicken und danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Yoco ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit Yoco verbunden und wird nicht von Yoco unterstützt.