VibeFox Viva Wallet for OpenCart — Hilfe

Voraussetzungen

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.

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

Währung: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK oder CHF. Die im Shop gewählte Währung des Kunden muss eine davon sein; bei anderen Währungen wird die Zahlungsart im Checkout ausgeblendet.

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer 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_viva_gateway-oc3-(version).ocmod.zip und das OpenCart-4-Paket wcp_viva_gateway.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 Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_viva_gateway-oc3-(version).ocmod.zip. Die Erweiterung hat 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 Viva Wallet Gateway und klicken Sie auf Install (die grüne +-Schaltfläche). Ihr Admin-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. Tragen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate (siehe License key).

4. Geben Sie die Zugangsdaten des Demo- und/oder Live-Kontos von Viva ein und richten Sie die Zahlungsquelle und den Webhook in Ihrem Viva-Konto ein (siehe Configuration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Führen Sie bei aktivem Test Mode eine Demo-Zahlung mit einer Viva-Demokarte durch und deaktivieren Sie dann Test Mode, um live zu gehen.

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_viva_gateway.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 Viva Wallet Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel, die Zugangsdaten von Viva, die Zahlungsquelle und den Webhook ein wie in den Schritten 3 bis 5 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Adressen des Viva-Kontos sind anders (siehe Configuration).

Eine neue Installation startet mit deaktivierter Zahlungsart und aktiviertem Testmodus.

Konfiguration

Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit. Die Abschnitte sind links aufgelistet; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Oberhalb der Einstellungen warnt die Seite, wenn der aktuelle Modus keine Client ID, kein Client Secret oder keinen Source Code hat (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 Standardwährung des Shops nicht unterstützt wird. Solange der Testmodus aktiv ist, zeigt sie Test mode is on: payments go to the Viva demo environment. Ohne das Recht, die Erweiterung zu ändern, zeigt die Seite die Einstellungen an, kann sie aber nicht speichern.

Beim Speichern darf Title nicht leer sein und höchstens 128 Zeichen lang sein (Enter a title for the payment method (at most 128 characters).), Sort Order muss eine ganze Zahl sein (Sort Order must be a whole number.), Total muss eine Zahl größer oder gleich 0 sein (Total: enter a number, 0 or greater.), und die gewählte Geo Zone sowie die Bestellstatus müssen existieren. Andernfalls wird nichts gespeichert, und die Seite zeigt den Fehler an. Beim Speichern der Einstellungen werden die zwischengespeicherten Viva-Zugriffstoken gelöscht, sodass die neuen Zugangsdaten sofort verwendet werden.

Viva Wallet

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

Title: der Name der Zahlungsart, den Kunden im Checkout sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Viva Wallet. Pflichtfeld, höchstens 128 Zeichen.

Description: der Text, der dem Kunden im Schritt Confirm Order oberhalb der Bestätigungsschaltfläche angezeigt wird. Standard: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: nutzt die Demo-Umgebung von Viva (demo.vivapayments.com). Neue Zahlungen und API-Aufrufe verwenden die Zugangsdaten des Demo-Kontos. Es wird kein echtes Geld belastet, und im Schritt Confirm Order sehen die Kunden (Test mode: use Viva demo cards, no real money is charged.) Standard: on. Deaktivieren Sie die Option, um mit dem Live-Konto echte Zahlungen anzunehmen. Bereits getätigte Zahlungen werden weiterhin in der Umgebung geprüft und erstattet, in der sie getätigt wurden.

Sort Order: die Position von Viva Wallet unter den Zahlungsarten im Checkout. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein; negative Zahlen sind erlaubt.

Geo Zone: bietet Viva Wallet nur für Rechnungsadressen in der gewählten Geo Zone an. Standard: All zones. Geo Zones werden unter System > Localisation > Geo Zones eingerichtet.

Total: der Checkout-Gesamtbetrag in der Standardwährung des Shops, den eine Bestellung erreichen muss, bevor Viva Wallet angeboten wird: eine Zahl größer oder gleich 0. Lassen Sie das Feld leer, um es bei jedem Betrag anzubieten.

Demo account (test mode) and Live account

Beide Abschnitte 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 Zugangsdaten für Smart Checkout (Client ID, Client Secret), die Merchant ID und den API Key. Der Source Code befindet sich unter Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): die OAuth-2.0-Client-ID von Smart Checkout des Kontos. Für Zahlungen erforderlich.

Client Secret (Demo) / Client Secret (Live): das OAuth-2.0-Client-Secret von Smart Checkout des Kontos. Für Zahlungen erforderlich.

Source Code (Demo) / Source Code (Live): der vierstellige Code der Zahlungsquelle des Kontos. Ihre Success-URL und Failure-URL müssen auf diesen Shop zeigen (siehe unten). Für Zahlungen erforderlich.

Merchant ID (Demo) / Merchant ID (Live): optional. Wird nur verwendet, um die URL-Überprüfung des Webhooks durch Viva zu beantworten.

API Key (Demo) / API Key (Live): optional. Wird nur verwendet, um die URL-Überprüfung des Webhooks durch Viva zu beantworten.

Gespeicherte Client Secrets und API Keys 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: am Ende des Abschnitts Live account. Markieren Sie ein gespeichertes Secret und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Return URLs and webhook

Addresses for the Viva account: dieses Feld zeigt die drei Adressen Ihres Shops, die Sie im Viva-Konto eintragen müssen. Sie werden aus der Storefront-Adresse Ihrer OpenCart-Installation gebildet und sehen auf OpenCart 3 etwa so aus: https://your-store/index.php?route=extension/payment/wcp_viva_gateway/success&, https://your-store/index.php?route=extension/payment/wcp_viva_gateway/fail& und https://your-store/index.php?route=extension/payment/wcp_viva_gateway/webhook, auf OpenCart 4 so: https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.success&, https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.fail& und https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.webhook. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen. Das & am Ende der Success- und Fail-Adressen ist notwendig: Viva hängt die Transaktion an die Adresse an, und ohne das & antwortet OpenCart mit einer Seite „nicht gefunden“.

Payment source: Erstellen Sie unter Sales > Online payments > Websites / apps eine Zahlungsquelle für die Domain Ihres Shops, in jedem Konto, das Sie verwenden. Als Success URL und Failure URL tragen Sie die Pfade nach der Domain der Success- und Fail-Adressen ein.

Webhook: Fügen Sie unter Settings > API Access > Webhooks die Webhook-Adresse für diese Ereignisse hinzu:

Viva prüft die URL vor dem Speichern. Die Erweiterung antwortet mit dem Verifizierungsschlüssel Ihres Kontos: Sie ruft ihn mit der Merchant ID und dem API Key des aktuellen Modus ab oder verwendet den unten eingetragenen Schlüssel. Webhooks bestätigen Zahlungen auch dann, wenn der Kunde den Browser schließt. Viva-Webhooks sind nicht signiert, daher vertraut die Erweiterung einem Webhook nie allein: Jede Zahlung wird über die Viva-API geprüft, bevor die Bestellung einen Status erhält. Ohne den Webhook erhält eine Bestellung nur dann einen Status, 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 der Merchant ID und dem API Key des aktuellen Modus abzurufen, oder fügen Sie hier den Verifizierungsschlüssel Ihres Viva-Kontos ein.

Order statuses

OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (eine fehlende Bestellung). Die Bestellung erhält erst einen Status, nachdem die Viva-Zahlung geprüft wurde. Die Statusfelder listen Ihre Bestellstatus aus OpenCart auf.

Order Status After Payment: der Status, den eine bezahlte Bestellung erhält. Er wird sofort mit einer einzigen Statusänderung gesetzt.

Processing Status: der Status einer bezahlten Bestellung für Default und Processing. Standard: Processing.

Complete Status: der Status einer bezahlten Bestellung für Completed. Standard: Complete.

On Hold Status: der Status einer bezahlten Bestellung für On Hold sowie einer Bestellung, deren Viva-Zahlung nicht zu Betrag oder Währung der Bestellung passt (zur Prüfung zurückgehalten, nicht bezahlt; die Notiz nennt den Grund). Standard: Pending, da OpenCart keinen Status On hold hat. Sie können unter System > Localisation > Order Statuses einen eigenen Status anlegen und hier auswählen.

Cancelled Order Status: Eine Viva-Zahlung für eine Bestellung in diesem Status öffnet sie nie wieder; eine Notiz fordert Sie auf, die Bestellung wiederherzustellen oder die Zahlung zu erstatten. Die Erweiterung setzt diesen Status nie. Standard: Canceled.

Refunded Status: wird gesetzt, nachdem die Zahlung im Tab der Bestellung vollständig erstattet wurde. Auch eine spätere Zahlung öffnet eine solche Bestellung nie wieder. Standard: Refunded.

Advanced Settings

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 nicht gespeichert: Die übrigen Einstellungen werden gespeichert, und die Seite zeigt Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.

Debug Logging: schreibt API-Anfragen in viva_wp_debug.log.php im Logs-Ordner von OpenCart (storage/logs, unter OpenCart 4 system/storage/logs). Die Datei lässt sich nicht über den Webbrowser öffnen. Schlüssel, Tokens und Kundendaten werden nicht protokolliert. Fehler werden immer protokolliert, auch wenn diese Option aus ist. 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 on Uninstall: wenn aktiviert, entfernt das Deinstallieren der Erweiterung die Einstellungen des Zahlungsgateways und das Protokoll. Bestellungen und ihre Zahlungsdaten (Viva-Zahlungsversuche, Erstattungen) werden nie gelöscht. Standard: off.

Import / Export

Export: Download JSON speichert die Einstellungen als JSON-Datei. Die 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.

Checkout

Im Schritt Payment Method wählt der Kunde die Zahlungsart (standardmäßig Viva Wallet). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung und den Hinweis You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. Unter 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 Checkout-Seite auf Confirm Order. Wenn der Kunde auf Confirm Order klickt, erstellt die Erweiterung eine Viva-Zahlungsbestellung für den Bestellbetrag in der Bestellwährung und leitet den Kunden zur Viva-Smart-Checkout-Seite weiter, mit Ihrer Brand Color, sofern eine festgelegt ist. Dort bezahlt der Kunde mit einer der Methoden, die in Ihrem Viva-Konto aktiviert sind. E-Mail, Name, Telefonnummer, Land und Shop-Sprache des Kunden werden an Viva übergeben. Die Zahlung erscheint bei Viva als OpenCart # mit der Bestellnummer und wird dem Kunden als Order, Bestellnummer, at und Ihr Shopname beschrieben. Die Viva-Zahlungsbestellung läuft nach 30 Minuten ab.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, nachdem Viva sie bestätigt hat: Die Erweiterung liest die Transaktion erneut über die Viva-API, bei der Rückkehr des Kunden und beim Webhook. Die Bestellung erhält danach ihren Status auf die übliche Weise von OpenCart, mit den üblichen Bestell-E-Mails und der Bestandsaktualisierung, und der Kunde sieht die Erfolgsseite der OpenCart-Bestellung. Ist die Zahlung noch nicht bestätigt, zeigt eine Seite Payment confirmation den Hinweis We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. mit den Schaltflächen Check again und Back to checkout. Der Warenkorb bleibt erhalten, bis die Zahlung bestätigt ist; der Webhook setzt den Bestellstatus, sobald Viva die Zahlung bestätigt. Unter OpenCart 4 öffnet beim Zurückkehren des Kunden von der Viva-Seite eine kurze Zwischenseite die Rückkehradresse Ihres Shops erneut, sodass Warenkorb und Kundensitzung erhalten bleiben.

Schlägt die Zahlung fehl oder bricht der Kunde auf der Viva-Seite ab, bleibt die Bestellung ohne Status und der Warenkorb erhalten. Der Kunde ist wieder im Checkout mit The Viva Wallet payment was not completed. Please try again or choose another payment method. bzw. The Viva Wallet payment was cancelled. You can try again or choose another payment method. und kann erneut bezahlen. Jeder neue Versuch startet eine neue Viva-Zahlungsbestellung. Ein Warenkorb wird nur einmal bezahlt: Ist er bereits durch eine andere Bestellung desselben Checkouts bezahlt, gelangt der Kunde direkt zur Erfolgsseite. Unter OpenCart 4 werden diese Meldungen über der Checkout-Seite angezeigt. OpenCart 3 legt jedes Mal eine neue Bestellung an, wenn der Schritt Confirm Order angezeigt wird, OpenCart 4 aktualisiert die Bestellung des Checkouts. Eine Änderung des Warenkorbs, auch eine neue Menge, gilt als neuer Warenkorb, der eine eigene Zahlung braucht.

OpenCart 4 hält die Bestellung im Checkout, bis die Erfolgsseite angezeigt wird. Nach einem fehlgeschlagenen oder abgebrochenen Zahlungsversuch bezahlt der Kunde dieselbe Bestellung erneut mit einer neuen Viva-Zahlungsbestellung. Wurde diese Bestellung inzwischen geschlossen (zum Beispiel haben Sie sie storniert) oder wurde sie für einen Warenkorb bezahlt, der sich seitdem geändert hat, kehrt der Kunde mit This order can no longer be paid. Please confirm your order again. zum Checkout zurück, und der nächste Confirm Order bezahlt eine neue Bestellung.

Kann Viva die Zahlung nicht starten, bleibt der Kunde im Schritt Confirm Order mit einer Meldung über der Schaltfläche: 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 im Protokoll festgehalten.

Die Rückkehrseiten zeigen die Erfolgsseite der Bestellung nur dem Kunden, der bezahlt hat. Alle anderen, die die Rückkehradresse öffnen, werden zur Bestellhistorie oder zum Checkout ohne Bestelldetails weitergeleitet.

Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist, da OpenCart Anfragen von Zahlungserweiterungen durchlässt. Unter OpenCart 4 lässt eine Startaktion der Erweiterung den Webhook und die Erfolgs- und Fehleradressen durch.

Die Erweiterung unterstützt nur Einmalzahlungen, die sofort auf der Viva-Seite belastet werden. Es gibt keine Vorautorisierung und Erfassung, keine Ratenzahlungen, keine gespeicherten Karten, keine Abonnements, kein Viva Native Checkout (Kartenfelder auf Ihrer eigenen Seite) und keine 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

Kein Status (fehlende Bestellung): Der Kunde wurde zu Viva weitergeleitet und hat nicht bezahlt, die Zahlung ist fehlgeschlagen oder wurde abgebrochen, oder Viva hat die Zahlung noch nicht abgeschlossen. Der Kunde kann erneut bezahlen. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt. Unter 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.

Order Status After Payment (Standard Processing): Die Zahlung wurde bestätigt. Eine Notiz zeigt den Betrag, die Transaktion, den Viva-Bestellcode, die Umgebung (Demo oder Live) und wie die Bestätigung erfolgte (Webhook oder Rückkehr des Kunden).

On Hold Status nach einer Abweichung (Standard Pending): Viva meldete einen anderen Betrag oder eine andere Währung als der Bestellbetrag. Die Bestellung wird nicht als bezahlt markiert, und die Notiz Viva Wallet payment held for review nennt den Grund. Vergleichen Sie die Zahlung im Viva-Dashboard mit der Bestellung und erfüllen oder erstatten Sie sie manuell. Trifft später eine passende Zahlung für dieselbe Bestellung ein, wechselt die Bestellung in den bezahlten Status.

Eine Zahlung, die für eine Bestellung im Status Cancelled Order Status oder Refunded Status eingeht, ändert den Bestellstatus nicht; eine Notiz fordert Sie auf, die Bestellung wiederherzustellen oder die Zahlung im Viva-Dashboard zu erstatten. Geht eine zweite Zahlung für eine bereits bezahlte Bestellung oder für eine andere Bestellung eines bereits bezahlten Warenkorbs ein, wird die Bestellung nicht verändert; eine Notiz an der bezahlten Bestellung fordert Sie auf, die Doppelzahlung im Viva-Dashboard zu erstatten.

Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht. Statusänderungen benachrichtigen den Kunden nicht von selbst; OpenCart sendet seine übliche Bestell-E-Mail, wenn eine bezahlte Bestellung erstmals einen Status erhält.

VibeFox Viva Wallet Gateway tab

Öffnen Sie unter Sales > Orders eine mit Viva Wallet bezahlte Bestellung. Unten auf der Bestellseite, neben History und Additional, zeigt der Tab VibeFox Viva Wallet Gateway den Viva order code, die Transaction ID mit einem Hinweis Demo bei Demo-Zahlungen, die Environment / Source Code, den Viva status, die Beträge Paid / refunded, das Erstattungsformular, den Erstattungsverlauf, die Viva payment attempts der Bestellung (wenn es mehr als einen gab) und die Viva Wallet notes der Bestellung. Der Tab wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.

Refunds

Geben Sie im Tab VibeFox Viva Wallet Gateway den Amount ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via Viva Wallet. Bestätigen Sie die Frage Refund this amount via Viva Wallet? This cannot be undone. Volle und teilweise Erstattungen werden für Bestellungen mit bestätigter Viva-Zahlung unterstützt. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Sie können bis zu dem Betrag erstatten, den Viva für die Zahlung belastet hat, auch wenn die Bestellung später bearbeitet wurde. Die Erstattung wird an das Konto gesendet, in dem die Zahlung getätigt wurde (Demo oder Live), in der Währung der Zahlung; daher müssen Client ID und Client Secret dieses Kontos eingetragen sein. Lehnt Viva die Erstattung ab, zeigt der Tab den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der Viva-Erstattungstransaktion dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded Status, ohne den Kunden zu benachrichtigen und ohne Waren an den Bestand zurückzugeben, ähnlich wie eine manuelle Statusänderung. Eine teilweise Erstattung ändert den Status nicht. Eine nach einer Abweichung zur Prüfung zurückgehaltene Bestellung hat keine bestätigte Zahlung und kann nicht über den Tab erstattet werden.

Produktrücksendungen unter Sales > Returns senden kein Geld über Viva zurück. Im Viva-Dashboard vorgenommene Erstattungen werden nicht importiert. Aktualisieren Sie die Bestellung bei Bedarf manuell.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Viva Wallet Gateway ist der erste Block auf Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit, oberhalb der Einstellungen. Tragen 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: opencart-payment-viva 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 Admin-Sprache (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 auf einer Domain: der 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 Viva Wallet Kunden im Checkout 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 Admin-Bereich 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 Admin-Bereichs. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin über den Viva-Webhook und die Rückkehr in den Shop 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 Admin-Bereichs 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

Viva Wallet erscheint nicht im Checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus seine Client ID, sein Client Secret und seinen Source Code hat (die Demo-Felder im Testmodus, die Live-Felder im Live-Modus). Die im Shop gewählte Währung muss eine von EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK oder CHF sein. Prüfen Sie außerdem, ob die Rechnungsadresse in der gewählten Geo Zone liegt und ob die Bestellung den in den Einstellungen festgelegten Total erreicht. Die Einstellungsseite zeigt eine Warnung an, wenn Zugangsdaten fehlen.

Die Zahlung ist erfolgt, aber die Bestellung bleibt ohne Status: Der Webhook funktioniert nicht. Prüfen Sie in Viva, ob der Webhook in dem Konto existiert, das Sie verwenden (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 eingetragen sind: Die Erweiterung benötigt sie, um die Zahlung zu prüfen. Aktivieren Sie Debug Logging und sehen Sie im Feld Log nach. Die Bestellung erhält ihren Status auch dann, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Der Kunde landet auf einer Seite „nicht gefunden“: Die Success URL oder Failure URL der Zahlungsquelle endet nicht mit &. Kopieren Sie die Pfade genau so, wie die Einstellungen sie anzeigen.

Viva kann die Webhook-URL nicht verifizieren: Tragen 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 in Viva. Um den Webhook des anderen Kontos zu verifizieren, schalten Sie zuerst Test Mode um oder tragen Sie den Schlüssel dieses Kontos ein.

Der Webhook antwortet mit einem Fehler: Viva zeigt die Antwort Ihres Shops an und wiederholt fehlgeschlagene Webhooks. verification_failed (HTTP 500) bedeutet, dass die Viva-API zur Prüfung der Zahlung nicht erreicht werden konnte oder der Bestellstatus nicht gesetzt 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 nach Confirm Order einen Fehler: Sehen Sie im Feld Log auf der Seite der Erweiterung nach. Eine falsche Client ID oder ein falsches Client Secret führt zur Meldung, dass Viva-Wallet-Zahlungen nicht verfügbar sind. Wenn Viva nicht erreicht werden kann oder die Zahlungsbestellung ablehnt, 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. This payment method is not available. bedeutet, dass die Checkout-Sitzung nicht mehr zur Bestellung passt: Der Kunde lädt den Checkout neu.

Der Kunde kehrt zurück und sieht We could not find your order. If you were charged, please contact us.: Der Viva-Bestellcode in der Rückkehradresse ist keine Zahlung dieses Shops, zum Beispiel weil die Zahlungsquelle eines anderen Shops hierher zeigt. Prüfen Sie die Success URL und die Failure URL der Zahlungsquelle.

Die Bestellung steht nach der Zahlung im Prüfstatus: Lesen Sie die Notizen im Tab VibeFox Viva Wallet Gateway (siehe Order statuses) und erfüllen Sie dann die Bestellung oder erstatten Sie die Zahlung.

Kein Erstattungsformular im Tab: Der Tab nennt den Grund: Die Bestellung hat keine bestätigte Viva-Zahlung (Transaction ID not found. Cannot process refund.), sie ist vollständig erstattet, die Zugangsdaten des Kontos der Zahlung fehlen oder Ihre Benutzergruppe hat kein Recht, die Erweiterung zu ändern.

Erstattung schlägt fehl mit This payment was made in the Viva demo (or live) environment: Client ID und Client Secret des Kontos, in dem die Zahlung getätigt wurde, sind nicht eingetragen. Tragen Sie sie ein und versuchen Sie es erneut. Andere Erstattungsfehler zeigen die Meldung von Viva an.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox Viva Wallet 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 Statusfelder des Abschnitts Order statuses, die bei einer Neuinstallation auf ihre Standardwerte zurückgesetzt werden. Die zwischengespeicherten Viva-Zugriffstoken und Webhook-Schlüssel werden immer entfernt. Unter OpenCart 4 werden außerdem das Ereignis der Erweiterung und ihre Startaktion immer entfernt; die Startaktion lässt im Wartungsmodus den Webhook und die Rückkehradressen durch. Ist Delete Data on Uninstall aktiv, werden die übrigen Zahlungsgateway-Einstellungen (Titel, Beschreibung, Testmodus, Zugangsdaten, Bestellstatus nach Zahlung, Markenfarbe, Protokollierung) und das Protokoll entfernt. Ist die Option aus, bleiben sie für eine spätere Neuinstallation erhalten. Die Viva-Zahlungsversuche und Erstattungen bleiben immer erhalten, sodass vorher bezahlte Bestellungen nach einer Neuinstallation weiter erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen.

Unter OpenCart 4 entfernen Sie die Dateien der Erweiterung ebenfalls, indem Sie nach der Deinstallation zu Extensions > Installer gehen, neben VibeFox Viva Wallet 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.

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