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

Shop-Währung: Südafrikanischer Rand (ZAR). Yoco akzeptiert nur ZAR. Bei jeder anderen Währung wird die Zahlungsart im Checkout nicht angeboten. 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. Es werden nur die geheimen Schlüssel eingetragen. Der Webhook wird vom Modul 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. Die Webhook-URL muss ein POST ohne Weiterleitungen annehmen.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert auf einer 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. Nach Abschluss des Uploads klicken Sie auf Configure, oder Sie suchen später VibeFox Yoco Pay Gateway in der Modulliste und klicken dort 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. Fügen Sie den geheimen Testschlüssel (sk_test_...) und, wenn Sie so weit sind, den geheimen Live-Schlüssel (sk_live_...) ein. Klicken Sie auf Save. Der Webhook wird für jeden Modus mit Schlüssel registriert.

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

Bei der Installation legt das Modul den Bestellstatus Yoco payment on hold an. PrestaShop aktiviert ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern warnt die Seite, wenn die Shop-Währung nicht ZAR ist (dann wird Yoco im Checkout nicht angeboten), und wenn der aktuelle Modus keinen geheimen Schlüssel hat, zum Beispiel mit Enter the test secret key to offer Yoco at checkout (test mode). Beim Speichern prüft das Modul die Schlüssel und Webhook-Geheimnisse und registriert die Webhooks. Entsprechende Meldungen erscheinen oben auf der Seite.

Yoco

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

Title: der Name der Zahlungsart, den Kunden im Checkout sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Card or Instant EFT (Yoco).

Description: der Text unter der Zahlungsart im Checkout. 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 API für beide Modi: Der Schlüssel entscheidet, ob eine Zahlung eine Test- 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 abgebucht; bezahlen Sie mit Yoco-Testkarten. Standard: eingeschaltet. Schalten Sie es aus, um echte Zahlungen anzunehmen. Solange es eingeschaltet ist, sehen Kunden unter der Zahlungsart 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. 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 nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Webhooks

Yoco bestätigt Zahlungen und Erstattungen an die URL, die in diesem Abschnitt unter Webhook URL angezeigt wird. Mit freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_yoco_pay/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Sie müssen den Webhook nicht im Yoco-Portal anlegen. Beim Speichern der Einstellungen registriert das Modul 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. Die Registrierung wird erneut ausgeführt, 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:

Das Modul verarbeitet diese Ereignisse (sie sind ebenfalls in diesem Abschnitt aufgeführt):

Webhooks ohne gültige Signatur werden abgelehnt. Ein Ereignis muss mit dem Geheimnis des Modus signiert sein, in dem die Zahlung erfolgte; so bestätigt ein Testschlüssel nie eine Live-Zahlung. Kopieren Sie die URL exakt so, wie die Einstellungen sie anzeigen, denn der Webhook muss Ihren Shop ohne Weiterleitung erreichen.

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 wie whsec_ gefolgt von Base64-Text aussehen. Jeder andere Wert wird nicht gespeichert, und der vorherige Wert bleibt erhalten.

Clear saved secrets: setzen Sie den Haken bei einem Schlüssel oder Geheimnis und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert. Das Leeren eines Webhook-Geheimnisses und Speichern registriert den Webhook erneut.

Advanced

Debug log: schreibt Yoco-Anfragen und Webhooks in logs/yoco_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. 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: aus.

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 des Moduls die Einstellungen, das Protokoll und die vom Modul bei Yoco registrierten Webhooks. Bestelldaten (Yoco-Checkout- und Zahlungs-IDs, Erstattungen) und der Bestellstatus Yoco payment on hold bleiben immer erhalten, da sie für Erstattungen benötigt werden. Standard: aus.

Checkout

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Card or Instant EFT (Yoco)) und bestätigt. Das Modul erstellt einen Yoco-Checkout für den Warenkorbbetrag in Cent und leitet den Kunden zur Yoco-Zahlungsseite weiter, wo er mit Karte oder Instant EFT bezahlt. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Yoco sie bestätigt: Das Modul fragt Yoco nach dem Checkout, wenn der Kunde zurückkommt, und erneut, wenn der signierte Webhook eingeht. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite 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 einer Schaltfläche Check again; der Webhook legt die Bestellung an, sobald er eintrifft.

Bricht der Kunde auf der Yoco-Seite ab, kehrt er zum Checkout 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. Der Warenkorb bleibt erhalten.

Vor einem neuen Zahlungsversuch für denselben Warenkorb prüft das Modul den vorherigen bei Yoco. Wurde er bereits bezahlt, wird die Bestellung ohne neue Zahlungsseite angelegt. Ist er noch offen, für denselben Betrag und vor weniger als 30 Minuten erstellt, erhält der Kunde erneut dieselbe Yoco-Seite. Andernfalls wird ein neuer Yoco-Checkout erstellt.

Kann Yoco die Zahlung nicht starten, bleibt der Kunde im Checkout mit Yoco could not start the payment. Please try again in a moment or choose another payment method., und der Grund wird ins Protokoll geschrieben. 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, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Zahlungen werden auf der Yoco-Seite sofort belastet. Das Modul hat 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

No order yet: der Kunde wurde zu Yoco geschickt und hat nicht bezahlt, auf der Yoco-Seite abgebrochen, oder Yoco hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted: die Zahlung wurde bestätigt. Sie wird mit der Yoco-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt den Betrag, die Yoco-Zahlungs- und Checkout-IDs, den Modus sowie die Art der Bestätigung (Rückkehr des Kunden, Webhook oder Prüfung vor einem neuen Zahlungsversuch).

Yoco payment on hold: Yoco hat einen anderen Betrag oder eine andere Währung gemeldet als der Warenkorbbetrag, zum Beispiel weil der Warenkorb nach Beginn der Zahlung in einem anderen Tab geändert wurde. Es wird keine Zahlung erfasst, die Notiz erklärt den Grund, 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 Payment accepted.

Cancelled or Refunded: eine Zahlung, die für eine solche Bestellung eingeht, ändert sie nicht. 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 ein, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, sie im Yoco-Portal zu erstatten.

Yoco-Zahlungsblock

Die Bestellseite zeigt einen Block Yoco payment mit den Yoco-Zahlungs- und Checkout-IDs, dem Status, dem bezahlten und erstatteten Betrag, einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf, den Zahlungsversuchen des Warenkorbs (wenn es mehr als einen gab) und den Yoco notes der Bestellung.

Erstattungen

Geben Sie im Block Yoco payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Yoco. Bestätigen Sie die Frage Refund this amount through Yoco? This cannot be undone. Volle und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattet wird aus dem von Yoco belasteten Betrag, daher können Sie höchstens den Betrag erstatten, den 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 dessen geheimer Schlüssel eingetragen sein. Eine nach einer verlorenen Antwort wiederholte Erstattung wird nicht doppelt ausgezahlt.

Eine erfolgreiche Erstattung wird mit der Yoco-Erstattungs-ID dem Erstattungsverlauf und den Notizen hinzugefügt. Eine volle Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Lehnt Yoco die Erstattung ab, zeigt der Block Yoco refused the refund: mit dem Grund, und es wird keine Erstattung erfasst. Meldet Yoco die Erstattung als ausstehend, zeigt der Block, dass sie noch aussteht. 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 mit Yoco payment on hold hat keinen bezahlten Checkout, der erstattet werden könnte; erstatten Sie sie im Yoco-Portal.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite 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, wird die Bestellung auf Refunded gesetzt. Eine Erstattung, die höher 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

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Yoco Pay Gateway ist der erste Block unter Modules > Module Manager > VibeFox Yoco Pay 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 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-yoco 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 funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-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 im Checkout nicht angezeigt. Versucht ein Kunde trotzdem zu zahlen, sieht er 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 im Checkout nicht testen. Ein Hinweis erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, 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 am Tag in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Deinstallation oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Yoco erscheint nicht im Checkout: 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. Die Warenkorbwährung muss ZAR sein und der Bestellbetrag mindestens R2,00. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Shop-Währung nicht ZAR ist. Prüfen Sie unter Payment > Preferences, ob das Modul für ZAR, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: 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 wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt, und wenn er erneut zu bezahlen versucht.

Webhook konnte nicht registriert werden: Zahlungen werden weiterhin bestätigt, wenn Kunden in den Shop zurückkehren. Beheben Sie den Grund aus der Meldung, zum Beispiel dass der Shop ü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 ins Protokoll geschrieben. 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 Serverzeit falsch ist: Signaturen werden nur innerhalb von 5 Minuten der 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 an: das ist normal. Die URL akzeptiert nur Anfragen von Yoco.

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 blieb erhalten.

Der Kunde sieht einen Fehler bei der Wahl von Yoco: sehen Sie im Feld Log auf der Modulseite nach. Yoco is not available at the moment. Please choose another payment method. bedeutet, dass der aktuelle Modus keinen geheimen Schlüssel hat.

Der Kunde wird darüber informiert, dass eine Zahlung geprüft werden muss: ein Versuch wurde mit einem anderen Betrag oder nach dem Abbruch der Bestellung bezahlt. Lesen Sie die Notizen im Block Yoco payment 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 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 PrestaShop wurde nichts erfasst. Hat Yoco die Erstattung doch verarbeitet, wiederholen Sie dieselbe Erstattung: Sie wird nicht doppelt erstattet.

Entwickler: der Hook actionYocoPCheckoutPayload erlaubt es einem anderen Modul, die Anfrage zu ändern, mit der der Yoco-Checkout erstellt wird.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Yoco Pay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data eingeschaltet, werden die Einstellungen, das Protokoll und die vom Modul bei Yoco registrierten Webhooks entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Yoco-Checkouts und -Erstattungen sowie der Bestellstatus Yoco payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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