VibeFox Viva Wallet for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

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

PHP: 8.0 oder neuer.

Viva-Konto: ein Viva-Händlerkonto. Für Tests können Sie ein Demo-Konto (demo.vivapayments.com) verwenden, für echte Zahlungen ein Live-Konto (www.vivapayments.com). Jedes Konto hat eigene Zugangsdaten. Für Zahlungen benötigen Sie die Smart-Checkout-Zugangsdaten (Client ID und Client Secret) und den Source Code einer Zahlungsquelle. Merchant ID und API Key sind optional: Sie werden nur benötigt, um die Verifizierung der Webhook-URL durch Viva zu beantworten.

Shop-Währung: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK oder CHF. In anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet.

Öffentliche HTTPS-Website: Für Webhooks muss Ihre Website über HTTPS aus dem Internet erreichbar sein.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert 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_viva_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Viva Wallet > Manage, oder klicken Sie auf der Plugins-Seite unter dem Plugin-Namen auf Settings.

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

5. Geben Sie die Zugangsdaten des Demo- und/oder Live-Kontos von Viva ein und richten Sie die Zahlungsquelle und den Webhook ein (siehe Konfiguration).

6. Aktivieren Sie Enable/Disable. Führen Sie bei aktiviertem Test Mode eine Demo-Zahlung mit einer Viva-Demokarte durch und deaktivieren Sie dann Test Mode, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Viva Wallet. Oberhalb der Felder warnt die Seite, wenn im aktuellen Modus Client ID, Client Secret oder Source Code fehlen (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered. bzw. Live im Live-Modus) und wenn die Shop-Währung nicht unterstützt wird. Bei aktivem Testmodus zeigt sie Test mode is on: payments go to the Viva demo environment. In der Liste der Zahlungsmethoden ist Viva Wallet als einrichtungsbedürftig markiert, bis der aktuelle Modus diese drei Werte hat.

General

Enable/Disable: Enable Viva Wallet payment gateway schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Viva Wallet.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (demo.vivapayments.com). Neue Zahlungen und API-Aufrufe verwenden die Zugangsdaten des Demo-Kontos. Es wird kein echtes Geld belastet, und an der Kasse endet die Beschreibung mit (Test mode: use Viva demo cards, no real money is charged.) Standard: aktiv. Deaktivieren Sie die Option, um echte Zahlungen über das Live-Konto anzunehmen. Bereits getätigte Zahlungen werden weiterhin in der Umgebung geprüft und erstattet, in der sie erfolgt sind.

Demo-Konto (Testmodus) und Live-Konto

Beide Bereiche haben dieselben Felder: einen Satz für das Demo-Konto und einen für das Live-Konto. Öffnen Sie in Ihrem Viva-Konto Settings > API Access und kopieren Sie die Smart-Checkout-Zugangsdaten (Client ID, Client Secret), die Merchant ID und den API Key. Der Source Code steht unter Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): die OAuth-2.0-Client-ID von Smart Checkout des Kontos. Pflichtfeld.

Client Secret (Demo) / Client Secret (Live): das OAuth-2.0-Client-Secret von Smart Checkout des Kontos. Pflichtfeld.

Source Code (Demo) / Source Code (Live): der 4-stellige Code der Zahlungsquelle des Kontos. Ihre Success URL und Failure URL müssen auf diesen Shop verweisen (siehe unten). Pflichtfeld.

Merchant ID (Demo) / Merchant ID (Live): optional. Wird nur verwendet, um die Verifizierung der Webhook-URL durch Viva zu beantworten.

API Key (Demo) / API Key (Live): optional. Wird nur verwendet, um die Verifizierung der Webhook-URL durch Viva zu beantworten.

Rücksprung-URLs und Webhook

Payment source: Legen Sie unter Sales > Online payments > Websites / apps für die Domain Ihres Shops eine Zahlungsquelle an, in jedem verwendeten Konto. Als Success URL und Failure URL tragen Sie die Pfade nach der Domain der beiden Adressen ein, die in den Einstellungen angezeigt werden und etwa so aussehen: https://your-site/wc-api/viva_payment_success/ und https://your-site/wc-api/viva_payment_fail/.

Webhook: Fügen Sie unter Settings > API Access > Webhooks die URL hinzu, die in den Einstellungen angezeigt wird und etwa so aussieht: https://your-site/wp-json/wc-viva-gateway/v1/webhook, für diese Ereignisse:

Transaction Payment Created: eine Zahlung wurde getätigt. Pflicht.

Transaction Failed: ein Zahlungsversuch ist fehlgeschlagen. Optional; fügt der Bestellung eine Notiz hinzu.

Viva prüft die URL vor dem Speichern. Das Plugin antwortet mit dem Verifizierungsschlüssel Ihres Kontos: Es ruft den Schlüssel mit Merchant ID und API Key des aktuellen Modus ab oder verwendet den unten eingegebenen Schlüssel. Webhooks bestätigen Zahlungen auch dann, wenn der Kunde den Browser schließt. Viva-Webhooks sind nicht signiert, daher vertraut das Plugin einem Webhook nie allein: Jede Zahlung wird über die Viva-API geprüft, bevor die Bestellung als bezahlt markiert wird. Ohne Webhook wird eine Bestellung nur bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Webhook Verification Key: optional. Lassen Sie das Feld leer, um den Schlüssel automatisch mit Merchant ID und API Key des aktuellen Modus abzurufen, oder fügen Sie hier den Verifizierungsschlüssel Ihres Viva-Kontos ein.

Erweiterte Einstellungen

Order Status After Payment: der Bestellstatus, der nach einer erfolgreichen Zahlung gesetzt wird. Der Status wird sofort gesetzt, ohne einen zweiten Statuswechsel.

Default (WooCommerce): In Bearbeitung oder Abgeschlossen für Bestellungen, die nur virtuelle herunterladbare Produkte enthalten (Standard).

Processing: Jede bezahlte Bestellung wird In Bearbeitung.

Completed: Jede bezahlte Bestellung wird Abgeschlossen.

On Hold: Jede bezahlte Bestellung wartet auf Ihre manuelle Prüfung.

Brand Color: ein 6-stelliger HEX-Farbcode für die Viva-Zahlungsseite, zum Beispiel 0000ff. Ein führendes # wird entfernt. Leer lassen für die Standardfarbe. Jeder andere Wert wird beim Speichern abgelehnt, der bisherige Wert bleibt erhalten.

Debug Logging: Enable logging schreibt API-Anfragen nach WooCommerce > Status > Logs, Quelle wcp_viva_gateway. Schlüssel und Kundendaten werden nicht protokolliert. Fehler werden immer protokolliert, auch wenn diese Option aus ist. Standard: aus.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Ist die Option aktiv, entfernt das Löschen des Plugins die Einstellungen, die Tabelle der Zahlungsversuche und die Plugin-Protokolle. Bestellnotizen und Bestelldaten bleiben erhalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Viva Wallet) und gibt die Bestellung auf. Das Plugin erstellt eine Viva-Zahlungsbestellung über den Bestellbetrag in der Bestellwährung und leitet den Kunden zur Viva-Smart-Checkout-Seite weiter. Dort bezahlt er mit einer der in Ihrem Viva-Konto aktivierten Methoden, zum Beispiel Karte, Apple Pay oder Google Pay. E-Mail, Name, Telefonnummer und Land des Kunden werden an Viva übergeben; die Seite öffnet sich in der Sprache Ihrer Website, sofern Viva diese unterstützt, andernfalls auf Englisch. Die Zahlung erscheint bei Viva als WooCommerce # und Bestellnummer. Die Viva-Zahlungsbestellung läuft nach 30 Minuten ab.

Nach der Zahlung kehrt der Kunde zur Seite „Bestellung eingegangen“ Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn Viva bestätigt: Das Plugin liest die Transaktion über die Viva-API erneut ein, bei der Rückkehr und beim Webhook. Ist die Zahlung noch nicht bestätigt, zeigt die Seite We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.

Schlägt die Zahlung fehl oder bricht der Kunde auf der Viva-Seite ab, ändert sich der Bestellstatus nicht. Der Kunde wird zur Seite Pay for order mit The Viva Wallet payment was not completed. Please try again or choose another payment method. oder The Viva Wallet payment was cancelled. You can try again or choose another payment method. geleitet und kann erneut zahlen.

Kann Viva die Zahlung nicht starten, sieht der Kunde Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (fehlende oder falsche Zugangsdaten) oder We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. Der technische Grund wird ins Protokoll geschrieben.

Die Zahlungsmethode funktioniert an der klassischen Kasse, am Kassen-Block und auf der Seite Pay for order, wo die Währung dieser Bestellung geprüft wird. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin akzeptiert nur Einmalzahlungen, die sofort auf der Viva-Seite belastet werden. Es unterstützt keine Vorautorisierung und Erfassung, keine Ratenzahlungen, gespeicherten Karten, WooCommerce Subscriptions, Viva Native Checkout (Kartenfelder auf der eigenen Seite) oder POS-Terminals. Startet der Kunde einen neuen Versuch, wird die alte, nicht bezahlte Viva-Zahlungsbestellung nicht storniert; Viva lässt sie nach 30 Minuten ablaufen.

Bestellungen und Erstattungen

Order statuses

Pending payment: Der Kunde wurde zu Viva weitergeleitet und hat noch nicht bezahlt, die Zahlung ist noch nicht bestätigt, oder die Zahlung ist fehlgeschlagen oder wurde abgebrochen. Eine Notiz zeigt die Viva-Zahlungsbestellung und die Umgebung (Demo oder Live). Fehlgeschlagene und abgebrochene Versuche werden den Bestellnotizen hinzugefügt, und der Kunde kann erneut zahlen.

Processing, Completed or On Hold: Die Zahlung wurde bestätigt. Der Status richtet sich nach Order Status After Payment. Die Bestellnotiz zeigt den Betrag, die Viva-Transaktions-ID, die Umgebung und wie die Zahlung bestätigt wurde (Webhook oder Rücksprung des Kunden).

On hold for review: Viva meldete einen anderen Betrag oder eine andere Währung als die Bestellsumme, zum Beispiel weil die Bestellung bearbeitet wurde, nachdem der Kunde mit der Zahlung begonnen hatte. Die Notiz Viva Wallet payment held for review nennt den Grund. Vergleichen Sie die Zahlung im Viva-Dashboard mit der Bestellung und schließen Sie sie ab oder erstatten Sie sie manuell.

Eine Zahlung für eine stornierte oder erstattete Bestellung ändert deren Status nicht; eine Notiz fordert Sie auf, die Bestellung wiederherzustellen oder die Zahlung im Viva-Dashboard zu erstatten. Kommt eine zweite Zahlung für eine bereits bezahlte Bestellung an, wird die Bestellung nicht erneut geändert; eine Notiz fordert Sie auf, das Duplikat im Viva-Dashboard zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Viva Wallet. Vollständige und teilweise Erstattungen werden für Bestellungen mit bestätigter Viva-Transaktion unterstützt. Die Erstattung wird an das Konto gesendet, über das die Zahlung erfolgte (Demo oder Live), in der Währung der Zahlung; daher müssen Client ID und Client Secret dieses Kontos eingegeben sein. Lehnt Viva die Erstattung ab, zeigt WooCommerce den Fehler an und es wird keine Erstattung verbucht. Eine erfolgreiche Erstattung wird mit der Viva-Erstattungstransaktion in den Bestellnotizen vermerkt.

Im Viva-Dashboard vorgenommene Erstattungen werden nicht importiert. Falls nötig, legen Sie in WooCommerce eine manuelle Erstattung ohne Refund via Viva Wallet an.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Viva Wallet. 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 funktioniert für eine Domain. Das Entfernen des Schlüssels von einer Website gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Viva Wallet 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 Zahlungsmethode weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. 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, funktioniert das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

Viva Wallet erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus seine Client ID, Client Secret und Source Code hat (die Demo-Felder im Testmodus, die Live-Felder im Live-Modus). Die Shop-Währung (auf der Seite Pay for order die Bestellwährung) muss eine der Währungen EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK oder CHF sein. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt.

Die Zahlung ist erfolgt, aber die Bestellung bleibt auf Pending payment: Der Webhook funktioniert nicht. Prüfen Sie bei Viva, ob der Webhook im verwendeten Konto existiert (Demo oder Live), ob seine URL genau der in den Einstellungen angezeigten entspricht und ob Transaction Payment Created ausgewählt ist. Prüfen Sie, ob Client ID und Client Secret des Kontos dieser Zahlung noch eingegeben sind: Das Plugin braucht sie, um die Zahlung zu verifizieren. Details stehen unter WooCommerce > Status > Logs, Quelle wcp_viva_gateway.

Viva kann die Webhook-URL nicht verifizieren: Geben Sie die Merchant ID und den API Key des aktuellen Modus ein (oder den Verifizierungsschlüssel selbst unter Webhook Verification Key), speichern Sie und verifizieren Sie dann erneut bei Viva. Um den Webhook des anderen Kontos zu verifizieren, wechseln Sie zuerst den Test Mode oder geben Sie den Schlüssel dieses Kontos ein.

Der Webhook antwortet mit einem Fehler: Viva zeigt die Antwort Ihres Shops und wiederholt fehlgeschlagene Webhooks. verification_failed (HTTP 500) bedeutet, dass die Viva-API zur Prüfung der Zahlung nicht erreicht werden konnte. busy (HTTP 503) bedeutet, dass die Bestellung im selben Moment von einer anderen Anfrage verarbeitet wurde. transaction_not_found (HTTP 404) bedeutet, dass die Transaktion im Konto dieser Zahlung nicht existiert, zum Beispiel wegen falscher Zugangsdaten. Ereignisse für Zahlungen anderer Shops auf demselben Viva-Konto werden mit ignored beantwortet.

Der Kunde sieht beim Aufgeben der Bestellung einen Fehler: Aktivieren Sie Debug Logging und sehen Sie unter WooCommerce > Status > Logs, Quelle wcp_viva_gateway, nach. Eine falsche Client ID oder ein falsches Client Secret oder ein fehlender Source Code führt zur Meldung, dass Viva-Wallet-Zahlungen nicht verfügbar sind. Kann Viva nicht erreicht werden oder lehnt es die Zahlungsbestellung ab, etwa weil der Source Code zu einem anderen Konto gehört, erhält der Kunde die Meldung, dass der Shop keine Verbindung zu Viva Wallet herstellen konnte.

Bestellung ist nach der Zahlung On hold: Lesen Sie die Bestellnotiz. Der gezahlte Betrag oder die Währung wich von der Bestellung ab. Schließen Sie die Bestellung ab oder erstatten Sie die Zahlung.

Erstattung schlägt fehl mit This payment was made in the Viva demo (or live) environment: Client ID und Client Secret des Kontos, über das die Zahlung erfolgte, sind nicht eingegeben. Geben Sie sie ein und versuchen Sie es erneut. Andere Erstattungsfehler zeigen den HTTP-Code und die Meldung von Viva.

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.

Für Entwickler: Der Filter viva_wp_supported_currencies aktiviert weitere Währungen, die Ihr Viva-Konto unterstützt, viva_wp_create_order_payload ändert die Anfrage für die Zahlungsbestellung (Betrag, Währung und Source Code müssen erhalten bleiben) und viva_wp_icon ändert das Symbol an der Kasse.

Deinstallation

Deaktivieren des Plugins behält alle Daten; nur die zwischengespeicherten Viva-Zugriffstoken werden entfernt. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins sowie die zwischengespeicherten Token und Webhook-Schlüssel werden immer entfernt. Die Einstellungen, die Tabelle der Zahlungsversuche und die Plugin-Protokolle (Protokolldateien, einschließlich rotierter, und Datenbankeinträge) 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.

Viva Wallet ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit Viva Wallet verbunden und wird nicht von Viva Wallet unterstützt.