VibeFox Yoco 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.

Shop-Währung: Südafrikanischer Rand (ZAR). Yoco akzeptiert nur ZAR. In jeder 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 vom Plugin registriert, und sein Signaturgeheimnis wird für Sie eingetragen.

Öffentlich erreichbare Website: Yoco sendet Webhooks an Ihre Website, daher muss sie aus dem Internet erreichbar sein. Die Webhook-URL muss ein POST ohne Weiterleitungen annehmen.

VibeFox-Lizenzschlüssel: erhältlich auf 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_yoco_pay per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Yoco > Manage.

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

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

6. Aktivieren Sie Enable/Disable. Führen Sie eine Testzahlung mit einer Yoco-Testkarte durch, solange Test mode aktiviert ist, und deaktivieren Sie danach Test mode, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Yoco. Oberhalb der Felder warnt die Seite, wenn die Shop-Währung nicht ZAR ist (Yoco wird dann an der Kasse nicht angeboten), und wenn für den aktuellen Modus kein geheimer Schlüssel hinterlegt ist. In der Liste der Zahlungsarten ist Yoco als einrichtungsbedürftig markiert, bis der aktuelle Modus einen geheimen Schlüssel hat. Beim Speichern prüft das Plugin die Schlüssel und Webhook-Geheimnisse und registriert die Webhooks. Hinweise dazu erscheinen oben auf der Seite.

Allgemein

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

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

Description: der Text unter der Zahlungsart an der Kasse. Standard: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus dem Yoco Business Portal unter Selling Online > Payment Gateway. Yoco hat eine einzige API für beide Modi: Der Schlüssel entscheidet, ob eine Zahlung ein Test- oder ein echter Vorgang ist. Der Testmodus verwendet nur den Testschlüssel, der Live-Modus nur den Live-Schlüssel.

Test mode: Use the test secret key (no real payments). Es wird kein echtes Geld belastet; bezahlen Sie mit Yoco-Testkarten. Standard: on. Deaktivieren Sie das Kästchen, um echte Zahlungen anzunehmen.

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

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

Ein Schlüssel, der nicht mit dem erwarteten Präfix beginnt, wird nicht gespeichert: Die Seite zeigt einen Fehler an und behält den bisherigen Wert. Meldet Yoco bei der Webhook-Registrierung, dass ein Schlüssel zum anderen Modus gehört, zeigt die Seite dies an.

Webhooks

Yoco bestätigt Zahlungen und Erstattungen an die Webhook-URL, die in diesem Abschnitt angezeigt wird. Sie hat das Format https://your-site/wc-api/yoco_pay_webhook/. Sie müssen den Webhook nicht im Yoco-Portal anlegen. Beim Speichern der Einstellungen registriert das Plugin die URL bei Yoco für jeden Modus, der einen geheimen Schlüssel, aber kein Webhook-Geheimnis hat, und trägt das Signaturgeheimnis in das Feld dieses Modus ein. Es 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 zeigt der Abschnitt den Status des Webhooks:

registered: das Plugin hat den Webhook registriert; seine Yoco-ID wird angezeigt. Steht im Hinweis, dass er für eine andere URL gilt, speichern Sie die Einstellungen, um ihn erneut zu registrieren.

secret entered manually: Sie haben das Geheimnis selbst eingefügt. Das Plugin ändert es nicht.

not registered: der Modus hat einen Schlüssel, aber noch keinen Webhook. Speichern Sie die Einstellungen, um ihn zu registrieren. Bis dahin werden Zahlungen nur bestätigt, wenn der Kunde zum Shop zurückkehrt.

no secret key: für den Modus ist kein geheimer Schlüssel hinterlegt.

Das Plugin verarbeitet diese Ereignisse:

payment.succeeded: eine Zahlung wurde geleistet. Das Plugin fragt bei Yoco den Checkout ab, bevor es die Bestellung als bezahlt markiert.

refund.succeeded: eine Erstattung wurde abgeschlossen, entweder aus WooCommerce oder im Yoco-Portal.

refund.failed: eine Erstattung ist fehlgeschlagen. Der Bestellung wird eine Notiz hinzugefügt.

Webhooks ohne gültige Signatur werden abgelehnt. Verwendet Ihre Website ein Sprachpräfix in den URLs, belassen Sie die URL genau so, wie die Einstellungen sie anzeigen, denn der Webhook muss Ihren Shop ohne Weiterleitung erreichen.

Test webhook secret: wird bei der Webhook-Registrierung automatisch eingetragen. Fügen Sie ein Geheimnis (whsec_...) nur ein, wenn Sie die Webhook-URL selbst registriert haben.

Live webhook secret: wird bei der Webhook-Registrierung automatisch eingetragen. Leeren Sie das Feld und speichern Sie, um den Webhook erneut zu registrieren.

Ein Webhook-Geheimnis muss die Form whsec_ gefolgt von Base64-Text haben. Jeder andere Wert wird nicht gespeichert, der bisherige bleibt erhalten.

Erweitert

Debug log: Log Yoco requests and webhooks schreibt Anfragen und Webhooks in WooCommerce > Status > Logs, Quelle wcp_yoco_pay. Fehler und Warnungen, etwa fehlgeschlagene Anfragen an Yoco und abgelehnte Webhooks, werden immer protokolliert. Schlüssel, Webhook-Geheimnisse und E-Mail-Adressen werden maskiert. Standard: off.

Delete data: Delete the settings and logs of this plugin when it is deleted. Die Deaktivierung löscht nie etwas. Bestelldaten (Yoco-Checkout- und Zahlungs-IDs) bleiben immer erhalten, da sie für Erstattungen benötigt werden. Standard: off.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Card or Instant EFT (Yoco)) und gibt die Bestellung auf. Im Testmodus zeigt die Kasse Test mode — use a Yoco test card; no real money is charged. Das Plugin erstellt einen Yoco-Checkout über den Bestellbetrag in Cent und leitet den Kunden auf die Yoco-Zahlungsseite weiter, wo er mit Karte oder Instant EFT bezahlt.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Yoco die Zahlung bestätigt: Das Plugin fragt bei Yoco den Checkout ab, wenn der Kunde zurückkehrt, und erneut, wenn der signierte Webhook eingeht. Hat Yoco die Zahlung noch nicht bestätigt, zeigt die Seite „Bestellung eingegangen“ We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

Storniert der Kunde auf der Yoco-Seite, bleibt die Bestellung unbezahlt, und der Kunde gelangt zur Seite Pay for order mit der Meldung The Yoco payment was cancelled. Your order is saved — you can pay again below 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 Kunde kann eine unbezahlte Bestellung über die Seite Pay for order erneut bezahlen. Vor einem neuen Versuch prüft das Plugin den vorherigen bei Yoco. Wurde er bereits bezahlt, wird die Bestellung abgeschlossen, ohne eine neue Zahlungsseite anzuzeigen. Ist er für denselben Betrag noch offen und vor weniger als 30 Minuten erstellt worden, erhält der Kunde erneut dieselbe Yoco-Seite.

Kann Yoco die Zahlung nicht starten, sieht der Kunde Yoco could not start the payment. Please try again in a moment or choose another payment method. und der Grund wird den Bestellnotizen hinzugefügt. Eine Bestellung unter R2,00 erhält Yoco requires an order total of at least R2.00.

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.

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

Bestellungen und Erstattungen

Bestellstatus

Pending payment: der Kunde wurde zu Yoco weitergeleitet und hat noch nicht bezahlt, auf der Yoco-Seite abgebrochen, oder Yoco hat die Zahlung noch nicht bestätigt.

Processing or Completed: die Zahlung wurde bestätigt. WooCommerce setzt „In Bearbeitung“ oder „Abgeschlossen“ für Bestellungen, die nur virtuelle, herunterladbare Produkte enthalten. Die Bestellnotiz zeigt den Betrag, die Yoco-Zahlungs- und Checkout-IDs, den Modus und die Art der Bestätigung (Rückkehr des Kunden, Webhook oder eine Prüfung vor einem neuen Zahlungsversuch). Die Transaktions-ID ist die Yoco-Zahlungs-ID.

On hold: Yoco hat einen anderen Betrag oder eine andere Währung als den Bestellbetrag gemeldet, zum Beispiel weil die Bestellung nach Beginn der Zahlung bearbeitet wurde. Die Notiz erklärt das, und der aus Yoco zurückkehrende 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.

Cancelled or Refunded: Eine Zahlung, die für eine solche Bestellung eingeht, ändert sie nicht. Eine Notiz fordert Sie auf, die Zahlung im Yoco-Portal zu erstatten oder die Bestellung manuell wiederherzustellen. Der aus Yoco zurückkehrende 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 ein, wird die Bestellung nicht erneut geändert. Eine Notiz fordert Sie auf, sie im Yoco-Portal zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf die Schaltfläche Refund via mit dem Titel Ihrer Zahlungsart (standardmäßig Card or Instant EFT (Yoco)). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird in dem Modus gesendet, in dem bezahlt wurde (Test oder Live), daher muss dessen geheimer Schlüssel hinterlegt sein. Eine Erstattung, die nach einer verlorenen Antwort wiederholt wird, wird nicht doppelt ausgezahlt.

Eine erfolgreiche Erstattung wird mit der Yoco-Erstattungs-ID in den Bestellnotizen vermerkt. Lehnt Yoco die Erstattung ab, zeigt WooCommerce Yoco refused the refund: mit dem Grund an, und es wird keine Erstattung erfasst. Meldet Yoco die Erstattung als ausstehend, zeigt WooCommerce an, dass sie noch aussteht, und erfasst nichts. Wiederholen Sie sie nicht: Sie wird der Bestellung hinzugefügt, sobald Yoco sie per Webhook bestätigt.

Im Yoco-Portal vorgenommene Erstattungen kommen über den Webhook refund.succeeded an und werden automatisch als WooCommerce-Erstattungen erfasst, ohne Lagerbestände zurückzubuchen. Eine Erstattung, die größer ist als der noch erstattungsfähige Betrag, wird nicht erfasst, und eine Notiz fordert Sie auf, 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

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Yoco. 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 aktiv 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 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. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert 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 Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

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

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 Live-Modus. Die Shop- oder Bestellwährung muss ZAR sein, und der Bestellbetrag muss mindestens R2,00 betragen. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Währung nicht ZAR ist.

Die Zahlung ist erfolgt, die Bestellung bleibt aber Pending payment: der Webhook funktioniert nicht. Öffnen Sie den Abschnitt Webhooks der Einstellungen und prüfen Sie den Status des Modus, den Sie verwenden. 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 eingetragen, prüfen Sie, ob es zum Webhook dieser URL und dieses Modus gehört. Die Bestellung wird auch bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt und wenn er 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 die Website über HTTPS 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 abgelehnt: abgelehnte Webhooks werden im Protokoll geschrieben, Quelle wcp_yoco_pay. 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.

The secret key must start with sk_test_ / sk_live_ error on save: 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 bisherige Wert bleibt erhalten.

Der Kunde erhält beim Aufgeben der Bestellung einen Fehler: lesen Sie die Bestellnotizen oder WooCommerce > Status > Logs, Quelle wcp_yoco_pay. Yoco is not available at the moment. Please choose another payment method. bedeutet, dass für den aktuellen Modus kein geheimer Schlüssel hinterlegt ist.

Dem Kunden wird mitgeteilt, dass eine Zahlung geprüft werden muss: ein früherer Versuch wurde mit einem anderen Betrag bezahlt oder nachdem die Bestellung storniert wurde. Lesen Sie die Bestellnotiz und erfüllen 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 Live-Modus, und der geheime Schlüssel dieses Modus ist nicht gesetzt. Tragen Sie ihn ein und versuchen Sie es erneut.

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

Der Lizenzblock zeigt einen Fehler: folgen Sie der 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

Die Deaktivierung des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen, die Webhook-Registrierungen bei Yoco und die Protokolle einschließlich rotierter Protokolldateien werden nur entfernt, wenn Delete data aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Yoco ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Yoco verbunden noch wird es von Yoco empfohlen.