VibeFox HyperPay for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

HyperPay-Konto: HyperPay stellt den Access Token und die Entity ID bereit, wenn Ihr Händlerkonto eingerichtet wird. Test- und Live-Zugangsdaten sind verschieden. 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, Kartendaten erreichen Ihren Server daher nie (PCI DSS SAQ A).

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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. Sie können auch den Ordner wcp_hyperpay_payment_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > HyperPay > Manage, oder klicken Sie auf der Seite Plugins unter dem Namen des Plugins auf Settings.

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

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

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

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

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > HyperPay. Oberhalb der Felder zeigt die Seite Der Testmodus ist aktiviert: Zahlungen gehen an das HyperPay-Testsystem, und es wird kein echtes Geld belastet. solange der Testmodus aktiv ist. Sie werden gewarnt, wenn der Access Token oder die Entity ID des aktuellen Modus fehlt (die Zahlungsmethode wird dann an der Kasse nicht angezeigt), und wenn der aktuelle Modus keinen gültigen Webhook-Schlüssel hat (Zahlungen werden dann nur bestätigt, wenn der Kunde in den Shop zurückkehrt). In der Liste der Zahlungsmethoden ist das Gateway als einrichtungsbedürftig markiert, bis der aktuelle Modus Access Token und Entity ID hat. Beim Speichern werden Leerzeichen aus den Zugangsdaten entfernt; die Seite zeigt einen Fehler, wenn ein Webhook-Schlüssel kein 64-stelliger hexadezimaler Schlüssel ist.

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

Title: der Titel, den der Kunde an der Kasse sieht. Standard: Credit/Debit Card (HyperPay).

Description: die Beschreibung, die der Kunde an der Kasse sieht. Standard: Pay securely using your credit or debit card.

API-Zugangsdaten

Access Token, Entity ID und Webhook-Schlüssel stellt HyperPay bereit, wenn Ihr Händlerkonto eingerichtet wird. Test- und Live-Zugangsdaten sind verschieden. Der Webhook-Schlüssel wird im HyperPay-Dashboard unter Administration > Webhooks angezeigt.

Test Mode: Enable Test Mode verwendet das HyperPay-Testsystem (eu-test.oppwa.com) und die Testzugangsdaten. Es wird kein echtes Geld belastet. Schalten Sie es aus, um echte Zahlungen mit den Live-Zugangsdaten anzunehmen (eu-prod.oppwa.com). Standard: ein.

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

Test Entity ID: die Entity ID des Testzahlungskanals.

Test Webhook Key: der 64-stellige hexadezimale Schlüssel zum Entschlüsseln der Webhook-Benachrichtigungen des Testsystems.

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 zum Entschlüsseln der Webhook-Benachrichtigungen des Live-Systems.

Webhook

Der Webhook informiert Ihren Shop über Zahlungen, auch wenn der Kunde den Browser schließt, bevor er zum Shop zurückkehrt. Fügen Sie im HyperPay-Dashboard (Administration > Webhooks) einen Webhook für Zahlungen mit der URL hinzu, die in diesem Abschnitt der Einstellungen angezeigt wird. Sie sieht so aus: https://your-site/wp-json/hyperpay-p/v1/webhook. Kopieren Sie danach den Webhook-Entschlüsselungsschlüssel 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 abgewiesen. Verarbeitet werden nur Zahlungsbenachrichtigungen, und die Zahlung muss zu einer Zahlungssitzung 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.

Zahlung

Transaction Type: so wird die Karte belastet.

Payment Brands: die Marken, die im Zahlungswidget angezeigt werden: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Standard: 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 Entität, die dieses Plugin nicht unterstützt.

Erweitert

Enable Logging: Log API requests and responses. Debug-Informationen werden unter WooCommerce > Status > Logs, Quelle wcp_hyperpay_payment_gateway, geschrieben. Fehler werden immer protokolliert. Protokolle enthalten keine Kartendaten, Schlüssel oder Kundendaten. Standard: aus.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Entfernt beim Löschen des Plugins die Einstellungen und Protokolldateien. Die bei Bestellungen gespeicherten HyperPay-Daten bleiben erhalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Credit/Debit Card (HyperPay)) und klickt auf Continue to payment. Die Bestellung wird angelegt, und der Kunde gelangt zur Seite Pay for order. Dort bereitet das Plugin eine HyperPay-Zahlungssitzung für den Bestellbetrag in der Bestellwährung vor und zeigt das HyperPay-Widget mit dem Hinweis Bitte schließen Sie Ihre Zahlung unten ab: an. Das Widget verwendet die Sprache Ihrer Website, sofern HyperPay sie unterstützt. Im Testmodus zeigt die Seite Testmodus: Verwenden Sie eine HyperPay-Testkarte, es wird keine echte Zahlung durchgeführt. Der Kunde gibt die Kartendaten im Widget ein.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Das Plugin prüft, ob die Zahlung zu einer der Zahlungssitzungen dieser Bestellung gehört, und fragt das Ergebnis mit einer serverseitigen Anfrage bei HyperPay ab. Die Bestellung wird erst als bezahlt markiert, wenn HyperPay die Zahlung bestätigt, 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 gleichzeitig eintreffen, werden nacheinander verarbeitet, sodass die Bestellung nie doppelt verarbeitet wird. Nach der Bestätigung landet der Kunde auf der Seite „Bestellung eingegangen“.

Wenn die Zahlung nicht erfolgreich war, kehrt der Kunde mit einer Meldung zur Seite Pay for order zurück: Zahlung fehlgeschlagen: und dem Grund von HyperPay, Die Zahlung wurde nicht abgeschlossen. Bitte versuchen Sie es erneut. oder Wir konnten Ihre Zahlung noch nicht bestätigen. Falls Ihnen ein Betrag belastet wurde, wird die Bestellung automatisch aktualisiert; andernfalls versuchen Sie es bitte erneut. Der Kunde kann auf derselben Seite erneut bezahlen. Kann das Widget nicht vorbereitet werden, sieht der Kunde eine kurze Meldung, zum Beispiel dass einige Rechnungsdaten vom Zahlungsanbieter nicht akzeptiert wurden, sowie die Schaltfläche Try Again. Die Details werden den Bestellnotizen hinzugefügt.

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 Zahlungsmethode funktioniert an der klassischen Kasse, im Warenkorb- und im Kassen-Block sowie auf der Seite Pay for order. Im Testmodus zeigt der Kassen-Block Testmodus: Es wird keine echte Zahlung durchgeführt. Sie ist kompatibel mit der High-Performance-Bestellspeicherung (HPOS) von WooCommerce.

Das Plugin unterstützt keine Erstattungen oder Stornierungen aus WooCommerce, keine gespeicherten Karten oder Tokenisierung, keine Abonnements, keine Apple-Pay-Domainverifizierung, keine separate Entität je Marke und keine Tabby-, Tamara- oder sonstigen Buy-now-pay-later-Methoden.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: der Kunde hat noch nicht bezahlt, das Widget nicht abgeschlossen oder HyperPay hat die Zahlung noch nicht bestätigt.

Processing: eine Sofortbelastung wurde bestätigt oder eine Vorautorisierung wurde erfasst. Bestellungen mit nur virtuellen, herunterladbaren Produkten werden auf Abgeschlossen gesetzt, das WooCommerce-Standardverhalten. Die Bestellnotiz zeigt den Ergebniscode von HyperPay, die Beschreibung und die Zahlungs-ID. Die Transaktions-ID ist die HyperPay-Zahlungs-ID. Hat HyperPay die Zahlung zur manuellen Prüfung markiert, steht das in der Notiz; prüfen Sie die Zahlung im HyperPay-Dashboard, bevor Sie versenden.

On hold (pre-authorization): der Betrag wurde reserviert. Erfassen Sie ihn mit der Bestellaktion Capture HyperPay payment oder im HyperPay-Dashboard; der Erfassungs-Webhook schließt die Bestellung danach ab.

On hold after payment: HyperPay hat einen anderen Betrag oder eine andere Währung als bei der Bestellung gemeldet (zum Beispiel wurde die Bestellung bearbeitet, nachdem die Zahlungsseite geöffnet wurde), die Zahlung ist bei HyperPay noch ausstehend oder die Zahlung ist eingegangen, nachdem die Bestellung storniert worden war. Die Bestellnotiz erklärt dies. Prüfen Sie die Zahlung im HyperPay-Dashboard und schließen Sie sie ab oder erstatten Sie sie.

Failed: HyperPay hat die Zahlung abgelehnt. Der Grund steht in der Bestellnotiz und wird dem Kunden angezeigt. Ein abgelehnter Versuch verändert nie eine Bestellung, die bereits bezahlt, reserviert, auf Wartend gesetzt oder storniert ist.

Cancelled: eine Vorautorisierung wurde im HyperPay-Dashboard storniert, und der Stornierungs-Webhook setzt die Bestellung auf Wartend zurück und storniert sie.

Trifft eine weitere erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, das Duplikat im HyperPay-Dashboard zu erstatten. Eine erfolgreiche Zahlung für eine erstattete Bestellung fügt nur eine Notiz hinzu.

Erfassung

Die Bestellaktion Capture HyperPay payment erscheint bei Bestellungen auf Wartend mit einer Vorautorisierung, die noch nicht erfasst wurde. Sie erfasst den aktuellen Bestellbetrag abzüglich der bereits in WooCommerce erfassten Erstattungen, im Modus, in dem die Vorautorisierung erfolgte. Nach einer erfolgreichen Erfassung wechselt die Bestellung zu In Bearbeitung. Lehnt HyperPay die Erfassung ab, werden der Ergebniscode und die Beschreibung angezeigt und den Bestellnotizen hinzugefügt. Das Stornieren (Void) einer Vorautorisierung erfolgt im HyperPay-Dashboard.

Erstattungen

Erstattungen aus WooCommerce werden nicht unterstützt. Erstatten Sie die Zahlung im HyperPay-Dashboard und erfassen Sie sie in WooCommerce mit Refund manually. Erstattungen und Chargebacks, die in HyperPay vorgenommen werden, fügt der Webhook der Bestellung als Notiz hinzu; der Bestellstatus ändert sich nicht.

Lizenzschlüssel

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

Ohne aktiven Schlüssel wird HyperPay Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde Diese Zahlungsmethode ist nicht verfügbar. Bitte wählen Sie eine andere aus. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Eine Erinnerung erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt, und Erfassungen funktionieren.

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

Fehlerbehebung

HyperPay erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus Access Token und Entity ID hat: die Test-Zugangsdaten im Testmodus, die Live-Zugangsdaten im Livemodus. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt auf Pending payment: 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 von Ihnen verwendeten Modus existiert, ob seine URL genau der in den Einstellungen angezeigten entspricht und ob sein Entschlüsselungsschlüssel im Webhook-Schlüsselfeld desselben Modus steht. Sehen Sie unter WooCommerce > Status > Logs nach, Quelle wcp_hyperpay_payment_gateway.

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 gesetzt. Fügen Sie den 64-stelligen Schlüssel in die Einstellungen ein. HyperPay wiederholt den Webhook.

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.

Das Zahlungsformular lädt nicht: lesen Sie die Bestellnotiz. Ein Konfigurationsfehler bedeutet meist einen falschen 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.

Bestellung ist On hold mit einer Notiz zu Betrags- oder Währungsabweichung: HyperPay hat eine Zahlung gemeldet, die nicht zum Bestellbetrag oder zur Währung passt, zum Beispiel weil die Bestellung bearbeitet wurde, nachdem die Zahlungsseite geöffnet wurde. Prüfen Sie die Zahlung im HyperPay-Dashboard und schließen Sie sie ab oder erstatten Sie sie.

Die Erfassung schlägt fehl: lesen Sie den Ergebniscode und die Beschreibung in der Bestellnotiz. Die Erfassung wird im Modus der Vorautorisierung gesendet, daher müssen die Zugangsdaten dieses Modus eingerichtet sein.

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. Wurde 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 hyperpay_p_icon ändert das Symbol der Zahlungsmethode.

Deinstallation

Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen, die temporären Daten des Plugins und die Protokolldateien werden nur entfernt, wenn Delete Data on Uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Die bei Bestellungen gespeicherten HyperPay-Daten bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

HyperPay ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit HyperPay verbunden noch wird es von HyperPay unterstützt.