VibeFox HyperPay 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 mit der OpenSSL-Erweiterung (sie entschlüsselt die Webhooks).

HyperPay-Konto: HyperPay stellt das Access Token und die Entity ID aus, wenn Ihr Händlerkonto eingerichtet wird. Test- und Live-Zugangsdaten sind unterschiedlich. Außerdem benötigen Sie einen Zahlungs-Webhook im HyperPay-Dashboard und dessen Entschlüsselungsschlüssel (Webhook-Schlüssel), der unter Administration > Webhooks angezeigt wird (siehe Konfiguration).

Kartendaten: Die Karte wird nur im HyperPay-Widget eingegeben, daher erreichen Kartendaten nie Ihren Server (PCI DSS SAQ A).

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

Installation

Der Download ist eine einzige 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_hyperpay_payment_gateway-oc3-(Version).ocmod.zip und das OpenCart-4-Paket wcp_hyperpay_payment_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_hyperpay_payment_gateway-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 HyperPay Payment 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. Fügen Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie das von HyperPay ausgestellte Test-Access-Token, die Entity ID und den Webhook-Schlüssel ein und lassen Sie Test Mode eingeschaltet.

5. Fügen Sie im HyperPay-Dashboard (Administration > Webhooks) einen Zahlungs-Webhook mit der URL hinzu, die im Abschnitt Webhook angezeigt wird, und kopieren Sie dessen Entschlüsselungsschlüssel in das Webhook-Schlüsselfeld desselben Modus.

6. Schalten Sie Enable/Disable ein, klicken Sie auf Save und führen Sie mit einer HyperPay-Testkarte eine Testzahlung durch. Geben Sie danach die Live-Zugangsdaten ein und schalten Sie Test Mode aus.

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_hyperpay_payment_gateway.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Erweiterungscode 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 HyperPay Payment Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und anschließend auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel, die HyperPay-Zugangsdaten und den Webhook ein, wie in den Schritten 3 bis 6 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Webhook-URL ist anders (siehe Webhook).

Bei einer neuen Installation ist die Zahlungsart zunächst ausgeschaltet und der Testmodus eingeschaltet.

Konfiguration

Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox HyperPay Payment Gateway > Edit. Die Abschnitte sind links aufgeführt; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Über den Einstellungen zeigt die Seite Test mode is on: payments go to the HyperPay test system and no real money is charged. an, solange der Testmodus eingeschaltet ist. Sie warnt, wenn das Access Token oder die Entity ID des aktuellen Modus fehlt (die Zahlungsart wird dann an der Kasse nicht angezeigt), und wenn der aktuelle Modus keinen gültigen Webhook-Schlüssel hat (Zahlungen werden dann erst bestätigt, wenn der Kunde in den Shop zurückkehrt). 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 haben, Transaction Type muss gültig sein, Sort Order muss eine ganze Zahl sein, Total muss eine Zahl von 0 oder mehr sein, und die Geo Zone sowie die Bestellstatus müssen existieren; andernfalls wird nichts gespeichert. Leerzeichen werden aus den Zugangsdaten entfernt. Die Einstellungen werden mit einer Warnung gespeichert, wenn ein Webhook-Schlüssel kein 64-stelliger hexadezimaler Schlüssel ist oder keine Zahlungsmarke ausgewählt ist.

HyperPay

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

Title: der Titel, den der Kunde an der Kasse sieht. Er ist außerdem der Name der Zahlungsart, der in der Bestellung gespeichert wird. Standard: Credit/Debit Card (HyperPay). Pflichtfeld.

Description: der Text, den der Kunde im Schritt Confirm Order über der Bestätigungsschaltfläche unter einem Kartensymbol sieht. Standard: Pay securely using your credit or debit card.

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

Geo Zone: HyperPay wird nur für Rechnungsadressen in der gewählten Geo Zone angeboten. Standard: All zones. Geo Zones werden unter System > Localisation > Geo Zones eingerichtet.

Total: der Kassenbetrag in der Standardwährung des Shops, den eine Bestellung erreichen muss, bevor HyperPay angeboten wird. Lassen Sie das Feld leer, um HyperPay bei jedem Betrag anzubieten.

API-Zugangsdaten

Das Access Token, die Entity ID und der Webhook-Schlüssel werden von HyperPay ausgestellt, wenn Ihr Händlerkonto eingerichtet wird. Test- und Live-Zugangsdaten sind unterschiedlich. Der Webhook-Schlüssel wird im HyperPay-Dashboard unter Administration > Webhooks angezeigt. Der Abschnitt enthält Links zur HyperPay-Website und zur Entwicklerdokumentation.

Test Mode: verwendet das HyperPay-Testsystem (eu-test.oppwa.com) und die Testzugangsdaten. Es wird kein echtes Geld belastet. Schalten Sie den Modus aus, um echte Zahlungen mit den Live-Zugangsdaten (eu-prod.oppwa.com) anzunehmen. Standard: eingeschaltet. Solange er eingeschaltet ist, sehen Kunden im Schritt Confirm Order den Hinweis Test mode: no real payment will be made.

Test Access Token: das Bearer-Token Ihres HyperPay-Testkontos.

Test Entity ID: die Entity ID des Test-Zahlungskanals.

Test Webhook Key: der 64-stellige hexadezimale Schlüssel, mit dem Webhook-Benachrichtigungen des Testsystems entschlüsselt werden.

Live Access Token: das Bearer-Token Ihres HyperPay-Live-Kontos.

Live Entity ID: die Entity ID des Live-Zahlungskanals.

Live Webhook Key: der 64-stellige hexadezimale Schlüssel, mit dem Webhook-Benachrichtigungen des Live-Systems entschlüsselt werden.

Gespeicherte Access-Tokens und Webhook-Schlüssel 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. Um einen gespeicherten Wert zu entfernen, setzen Sie unter dem Feld den Haken bei Clear the saved value on save und klicken Sie auf Save.

Webhook

Der Webhook informiert Ihren Shop über Zahlungen, auch wenn der Kunde den Browser schließt, bevor er in den Shop zurückkehrt. Fügen Sie im HyperPay-Dashboard (Administration > Webhooks) einen Webhook für Zahlungen mit der URL hinzu, die in diesem Abschnitt unter Webhook URL angezeigt wird. Unter OpenCart 3 lautet sie https://your-store/index.php?route=extension/payment/wcp_hyperpay_payment_gateway/webhook, unter OpenCart 4 https://your-store/index.php?route=extension/wcp_hyperpay_payment_gateway/payment/wcp_hyperpay_payment_gateway.webhook. Sie wird aus der Storefront-Adresse Ihrer OpenCart-Installation gebildet. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Kopieren Sie anschließend den Entschlüsselungsschlüssel des Webhooks in Test Webhook Key oder Live Webhook Key, je nach Modus.

HyperPay-Webhooks sind verschlüsselt (AES-256-GCM). Ein Webhook, der sich mit Ihren Schlüsseln nicht entschlüsseln lässt, wird abgelehnt. Verarbeitet werden nur Zahlungsbenachrichtigungen, und die Zahlung muss zu einer Kasse einer Ihrer Bestellungen gehören, die im selben Modus wie der Schlüssel erstellt wurde, der sie entschlüsselt hat. HyperPay-Testbenachrichtigungen werden bestätigt. Der Webhook meldet außerdem Erfassungen, Stornierungen, Erstattungen und Chargebacks, die im HyperPay-Dashboard vorgenommen wurden (siehe Bestellungen und Erstattungen). Ohne den Webhook wird eine Zahlung erst bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt. Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist: OpenCart 3 lässt Anfragen von Zahlungserweiterungen durch, und unter OpenCart 4 fügt die Erweiterung eine Startaktion hinzu, die den Webhook und die Rückkehr des Kunden von HyperPay durchlässt.

Payment

Transaction Type: wie die Karte belastet wird.

Payment Brands: die Marken, die im Zahlungswidget angezeigt werden: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Standard: VISA und Mastercard. Ist keine Marke ausgewählt, warnt die Seite und das Widget zeigt VISA und Mastercard. Wählen Sie nur Marken aus, die HyperPay für Ihre Entity ID aktiviert hat; mada, STC Pay und Apple Pay verwenden oft eine eigene Entity, die diese Erweiterung nicht unterstützt.

Bestellungen

OpenCart erstellt die Bestellung im Schritt Confirm Order ohne Status (eine fehlende Bestellung). Die Bestellung erhält erst dann einen Status, wenn HyperPay die Zahlung bestätigt hat. Eine abgelehnte oder abgebrochene Zahlung lässt die Bestellung ohne Status, und der Warenkorb bleibt erhalten. Jedes der folgenden Felder listet Ihre OpenCart-Bestellstatus auf. OpenCart hat keinen Status „On hold“, daher ist für drei davon Ausstehend als Standard vorgegeben; eigene Status können Sie unter System > Localisation > Order Statuses anlegen und hier auswählen.

Order Status After Payment: wird gesetzt, wenn HyperPay eine Belastung mit dem richtigen Betrag und der richtigen Währung bestätigt oder eine Vorautorisierung erfasst wird. Standard: In Bearbeitung.

Authorized (Capture Required) Status: eine Vorautorisierung hat den Betrag reserviert; erfassen Sie ihn im Reiter der Bestellung. Eine Stornierung im HyperPay-Dashboard storniert die Bestellung, solange sie diesen Status hat. Standard: Ausstehend.

Awaiting Payment Status: HyperPay hat eine Zahlung gemeldet, die auf eine Bestätigung wartet; der Webhook bestätigt sie später. Standard: Ausstehend.

On Hold (Review) Status: der gezahlte Betrag oder die Währung weicht von der Bestellung ab, oder eine Zahlung ist eingegangen, nachdem die Bestellung storniert wurde. Ein Hinweis erklärt den Grund. Standard: Ausstehend.

Canceled Status: wird gesetzt, wenn die Vorautorisierung in HyperPay storniert wird. Eine Zahlung für eine Bestellung in diesem Status setzt sie auf Prüfung, statt sie wieder zu öffnen. Standard: Storniert.

Refunded Status: eine Zahlung für eine Bestellung in diesem Status wird nur vermerkt; die Bestellung wird nicht verändert. Standard: Erstattet.

Erweitert

Enable Logging: protokolliert API-Anfragen und -Antworten in hyperpay_p_debug.log.php im Protokollordner von OpenCart (storage/logs). Die Datei kann nicht über das Web geöffnet werden und wird bei 5 MB nach hyperpay_p_debug.old.log.php verschoben. Fehler und Warnungen werden immer protokolliert. Protokolle enthalten keine Kartendaten, Schlüssel oder Kundendaten. 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 on Uninstall: ist die Option eingeschaltet, entfernt die Deinstallation der Erweiterung die Einstellungen und die Protokolldateien. Bestellungen und HyperPay-Zahlungsversuche bleiben immer erhalten, weil späte Webhooks und Erfassungen für bestehende Bestellungen sie benötigen. Standard: aus.

Import / Export

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

Import: Fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Gespeicherte Access-Tokens und Webhook-Schlüssel bleiben erhalten.

Kasse

Im Schritt Payment Method wählt der Kunde die Zahlungsart (standardmäßig Credit/Debit Card (HyperPay)). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung. OpenCart erstellt die Bestellung in diesem Schritt, weiterhin ohne Status. Klickt der Kunde auf Confirm Order, bereitet die Erweiterung eine HyperPay-Kasse für den Bestellbetrag in der Bestellwährung vor und öffnet die Seite HyperPay payment Ihres Shops mit dem HyperPay-Widget und Please complete your payment below:. Das Widget verwendet die Sprache des Kunden, sofern HyperPay sie unterstützt. Im Testmodus zeigt die Seite Test mode: use a HyperPay test card, no real payment will be made. Der Kunde gibt die Kartendaten im Widget ein oder folgt Choose another payment method zurück zur Kasse. Wird die Seite neu geladen, wird dieselbe Kasse bis zu 25 Minuten lang wiederverwendet, solange sich der Bestellbetrag nicht ändert; danach wird eine neue Kasse vorbereitet.

Unter OpenCart 4 wählt der Kunde die Zahlungsart über die Schaltfläche Choose im Block der Zahlungsart im Fenster Payment method options und klickt unten auf der Kassenseite auf Confirm Order. Standardmäßig fragt OpenCart 4 nicht nach einer Zahlungsadresse; die Erweiterung sendet dann die Lieferadresse als Rechnungsadresse an HyperPay.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Erweiterung prüft, dass die Zahlung zu einer Kasse dieser Bestellung gehört, und fragt das Ergebnis bei HyperPay über eine Server-zu-Server-Anfrage ab, und zwar im Modus, in dem die Kasse erstellt wurde. Die Bestellung wird erst als bezahlt markiert, wenn HyperPay die Zahlung bestätigt hat: entweder durch diese Anfrage oder durch den Webhook. Betrag und Währung müssen mit der Bestellung übereinstimmen. Eine Rückkehr und ein Webhook, die im selben Moment eintreffen, sowie Ergebnisse für zwei Bestellungen desselben Warenkorbs werden nacheinander verarbeitet, sodass die Zahlung nie doppelt verbucht wird. Die Bestellung erhält ihren Status dann 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 nicht durchgegangen, kehrt der Kunde mit einer Meldung zur Kasse zurück: Payment failed: und dem Grund von HyperPay, Payment was not completed. Please try again. oder We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Der Warenkorb bleibt erhalten, und der Kunde kann erneut zahlen. Kann das Zahlungsformular nicht vorbereitet werden, bleibt der Kunde im Schritt Confirm Order mit einer kurzen Meldung, zum Beispiel dass der Zahlungsanbieter einige Rechnungsdaten nicht akzeptiert hat oder dass das Zahlungsformular wegen eines Konfigurationsfehlers nicht verfügbar ist. Der technische Grund wird im Protokoll festgehalten.

Unter OpenCart 4 werden diese Meldungen oberhalb der Kassenseite angezeigt. OpenCart 3 erstellt jedes Mal, wenn der Schritt Confirm Order angezeigt wird, eine neue Bestellung; OpenCart 4 aktualisiert die Bestellung der Kasse, daher bezahlt der Kunde nach einer abgelehnten Zahlung dieselbe Bestellung mit einem neuen Zahlungsversuch. Wurde derselbe Warenkorb bereits über eine andere Bestellung bezahlt, gelangt der Kunde zur Erfolgsseite, statt erneut zu zahlen. Eine Änderung des Warenkorbs, auch eine neue Menge, gilt als neuer Warenkorb, der eine eigene Zahlung benötigt.

OpenCart 4 behält die Bestellung in der Kasse, bis die Erfolgsseite angezeigt wird. Wurde diese Bestellung inzwischen ohne Zahlung geschlossen (etwa weil Sie sie storniert haben), wird der Kunde mit Payment failed. Please try again or use another card. zurück zur Kasse geschickt. Wurde sie bezahlt und danach storniert oder erstattet, lautet die Meldung Your previous order was closed by the store. Please confirm the order again to pay with a new order. Ist sie bereits bezahlt und enthält der Warenkorb jetzt einen neuen Kauf, lautet die Meldung Your previous order #(Nummer) has already been placed. Your cart has changed: please confirm the new order to pay for it. In jedem Fall bezahlt das nächste Confirm Order eine neue Bestellung des Warenkorbs. Eine bezahlte Bestellung wird nie als bezahlt für einen anderen Warenkorb angezeigt.

Beträge werden mit zwei Dezimalstellen übermittelt, wie es die HyperPay-API verlangt. Bei Währungen mit drei Dezimalstellen (KWD, BHD, JOD, OMR) wird der Bestellbetrag auf zwei Dezimalstellen gerundet.

Die Erweiterung bietet keine Erstattungen oder Stornierungen aus OpenCart, keine gespeicherten Karten oder Tokenisierung, keine Abonnements, keine Apple-Pay-Domainverifizierung, keine eigene Entity pro Marke und keine Tabby-, Tamara- oder andere Buy-now-pay-later-Methoden.

Bestellungen und Erstattungen

Bestellstatus

No status (missing order): der Kunde wurde zur Zahlungsseite geschickt und hat nicht bezahlt, die Zahlung wurde abgelehnt, oder HyperPay hat die Zahlung noch nicht bestätigt. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt.

Order Status After Payment (default Processing): eine Belastung wurde bestätigt oder eine Vorautorisierung erfasst. Eine Notiz zeigt den Ergebniscode, die Beschreibung und die Zahlungs-ID von HyperPay. Hat HyperPay die Zahlung zur manuellen Prüfung markiert, weist die Notiz darauf hin; prüfen Sie sie im HyperPay-Dashboard, bevor Sie versenden.

Authorized (Capture Required) Status (default Pending): der Betrag wurde durch eine Vorautorisierung reserviert. Erfassen Sie ihn im Reiter der Bestellung oder im HyperPay-Dashboard; der Erfassungs-Webhook setzt die Bestellung danach auf Order Status After Payment.

Awaiting Payment Status (default Pending): HyperPay hat die Zahlung als ausstehend gemeldet. Die Bestellung wechselt zu Order Status After Payment, sobald HyperPay die Zahlung bestätigt.

On Hold (Review) Status (default Pending): HyperPay hat einen anderen Betrag oder eine andere Währung als bei der Bestellung gemeldet (zum Beispiel wurde der Warenkorb geändert, nachdem die Zahlungsseite geöffnet wurde), oder die Zahlung ist eingegangen, nachdem die Bestellung storniert wurde. Die Notiz erklärt es. Prüfen Sie die Zahlung im HyperPay-Dashboard und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Canceled Status (default Canceled): eine Vorautorisierung wurde im HyperPay-Dashboard storniert, und der Storno-Webhook storniert die autorisierte Bestellung.

Ein abgelehntes Ergebnis ändert nie eine Bestellung, die bereits einen Status hat. Trifft eine weitere erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein oder wird eine andere Bestellung eines bereits bezahlten Warenkorbs bezahlt, bleibt die bezahlte Bestellung unverändert. Eine Notiz fordert Sie auf, das Duplikat im HyperPay-Dashboard zu erstatten. Eine erfolgreiche Zahlung für eine Bestellung im Refunded Status fügt nur eine Notiz hinzu.

Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht.

Reiter VibeFox HyperPay Payment Gateway

Öffnen Sie unter Sales > Orders eine mit HyperPay bezahlte Bestellung. Am Ende der Bestellseite, neben History und Additional, zeigt der Reiter VibeFox HyperPay Payment Gateway die Zahlungs-ID (und nach einer Erfassung die Erfassungs-ID) mit einem Hinweis Test mode bei Testzahlungen, den Transaktionstyp, die Kassen-ID, die Händler-Transaktions-ID, den an HyperPay gesendeten Betrag, das Ergebnis und die HyperPay notes der Bestellung. Der Reiter wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.

Erfassung

Bei einer vorautorisierten Bestellung, die noch nicht erfasst ist, zeigt der Reiter Capture payment mit dem Betrag an. Klicken Sie darauf und bestätigen Sie Capture the pre-authorized amount through HyperPay?. Der aktuelle Bestellbetrag wird im Modus erfasst, in dem die Vorautorisierung erfolgt ist; daher müssen dessen Access Token und Entity ID gesetzt sein. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Nach einer erfolgreichen Erfassung erhält die Bestellung Order Status After Payment, und die Erfassungs-ID wird dem Reiter und den Notizen hinzugefügt. Der Status wird direkt geschrieben, ohne Bestell-E-Mails oder Bestandsaktualisierung. Lehnt HyperPay die Erfassung ab, werden Ergebniscode und Beschreibung angezeigt und den Notizen hinzugefügt, und die Bestellung bleibt autorisiert. Ein Doppelklick erfasst nicht zweimal. Das Zurücknehmen (Voiden) einer Vorautorisierung erfolgt im HyperPay-Dashboard.

Erstattungen

Erstattungen aus OpenCart werden nicht unterstützt. Produktrücksendungen unter Sales > Returns senden kein Geld über HyperPay zurück. Erstatten Sie die Zahlung im HyperPay-Dashboard. Erstattungen und Chargebacks, die in HyperPay vorgenommen werden, werden vom Webhook als Notiz zur Bestellung hinzugefügt; der Bestellstatus ändert sich nicht. Aktualisieren Sie ihn bei Bedarf manuell.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox HyperPay Payment Gateway ist der erste Block unter Extensions > Extensions > Payments > VibeFox HyperPay Payment 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 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 zur erneuten Statusprüfung, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-payment-hyperpay und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung Modify für die Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (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. Nachdem sich die Shop-Adresse geändert hat oder 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 HyperPay Kunden an der Kasse nicht angezeigt. Wird eine Zahlung dennoch gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Admin-Benutzer, der sich im selben Browser im Admin angemeldet hat, sieht die Zahlungsart im Shop weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. Unter OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher ist 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 im Admin. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt, und Erfassungen und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, Updates und Support erfordern jedoch eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard oder die Seite Edit im Admin öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal wöchentlich. Ein Cronjob wird nicht benötigt. Das Deinstallieren der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

HyperPay erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus sein Access Token und seine Entity ID hat: die Test-Zugangsdaten im Testmodus, die Live-Zugangsdaten im Live-Modus. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen. Prüfen Sie außerdem, ob die Rechnungsadresse in der gewählten Geo Zone liegt und ob die Bestellung den eingestellten Total-Betrag erreicht.

Die Zahlung ist erfolgt, aber die Bestellung bleibt ohne Status: der Webhook funktioniert nicht, und der Kunde ist nicht in den Shop zurückgekehrt. Prüfen Sie im HyperPay-Dashboard, ob der Zahlungs-Webhook für den verwendeten Modus existiert, ob seine URL genau der unter Webhook URL angezeigten entspricht und ob sein Entschlüsselungsschlüssel im Webhook-Schlüsselfeld desselben Modus steht. Schalten Sie Enable Logging ein und sehen Sie sich das Feld Log auf der Erweiterungsseite an.

Der Webhook antwortet Decryption failed: der Webhook-Schlüssel gehört zu einem anderen Webhook oder einem anderen Modus. Kopieren Sie den Schlüssel erneut aus dem HyperPay-Dashboard.

Der Webhook antwortet Webhook key not configured: es ist kein gültiger Webhook-Schlüssel hinterlegt. Fügen Sie den 64-stelligen Schlüssel in die Einstellungen ein. HyperPay wiederholt den Webhook.

Der Webhook antwortet Busy, retry later: die Bestellung wurde im selben Moment von einer anderen Anfrage verarbeitet, oder der Bestellstatus konnte nicht gesetzt werden. HyperPay wiederholt den Webhook. Der Grund steht im Protokoll.

Das Protokoll zeigt Webhook ignored: die Zahlung gehört nicht zu einer Bestellung dieses Shops oder wurde im anderen Modus getätigt. Test- und Live-Zahlungen werden getrennt gehalten.

Die Webhook-URL zeigt im Browser Method not allowed: das ist normal. Die URL akzeptiert nur POST-Anfragen von HyperPay.

Das Zahlungsformular lädt nicht: prüfen Sie das Protokoll. Ein Konfigurationsfehler bedeutet meist ein falsches Access Token oder eine falsche Entity ID für den aktuellen Modus. Eine Meldung zu Rechnungsdaten bedeutet, dass HyperPay einige Kundendaten nicht akzeptiert hat. Stellen Sie sicher, dass die ausgewählten Payment Brands für Ihre Entity ID aktiviert sind.

Der Kunde sieht The payment session was not found. Please confirm the order again.: der Link zur Zahlungsseite ist für diese Bestellung nicht mehr gültig. Der Kunde bestätigt die Bestellung an der Kasse erneut.

Order is in the on hold status: lesen Sie die Notizen im Reiter der Bestellung (siehe Bestellstatus), prüfen Sie die Zahlung im HyperPay-Dashboard und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Erfassung schlägt fehl: lesen Sie Ergebniscode und Beschreibung im Reiter und in den Notizen. Die Erfassung wird im Modus der Vorautorisierung gesendet; daher müssen dessen Zugangsdaten gesetzt sein, andernfalls meldet der Reiter, dass Access Token / Entity ID dieses Modus leer sind.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox HyperPay Payment 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. Unter OpenCart 4 werden außerdem dessen Ereignisse und seine Startaktion entfernt, die im Wartungsmodus den Webhook und die Rückkehr des Kunden durchlässt. Ist Delete Data on Uninstall eingeschaltet, werden die übrigen Einstellungen (Titel, Beschreibung, Testmodus, Zugangsdaten, Webhook-Schlüssel, Transaktionstyp, Marken, Protokollierung) und die Protokolldateien entfernt. Ist die Option ausgeschaltet, bleiben sie für eine spätere Neuinstallation erhalten. Die HyperPay-Zahlungsversuche bleiben immer erhalten, sodass späte Webhooks und Erfassungen bestehender Bestellungen nach einer Neuinstallation weiterhin funktionieren. Bestehende Bestellungen behalten ihre Zahlungsnotizen.

Um unter OpenCart 4 auch die Dateien der Erweiterung zu entfernen, gehen Sie nach der Deinstallation zu Extensions > Installer, klicken Sie in der Liste der installierten Erweiterungen neben VibeFox HyperPay Payment Gateway auf Uninstall (die orangefarbene −-Schaltfläche) und dann auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

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