VibeFox HyperPay for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer mit der Erweiterung OpenSSL (sie entschlüsselt die Webhooks). Ohne sie lässt sich das Modul nicht installieren.

HyperPay-Konto: HyperPay stellt Access Token und 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, daher erreichen Kartendaten nie Ihren Server (PCI DSS SAQ A).

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt für eine Domain.

Installation

1. Gehen Sie im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox HyperPay Payment Gateway in der Modulliste und klicken Sie auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel im Feld License key im Lizenzblock oben auf der Seite Configure 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 aktiviert.

5. Fügen Sie im HyperPay-Dashboard (Administration > Webhooks) einen Zahlungs-Webhook mit der URL aus dem Abschnitt Webhook hinzu und kopieren Sie dessen Entschlüsselungsschlüssel in das Feld für den Webhook-Schlüssel desselben Modus.

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

Bei der Installation legt das Modul drei Bestellstatus an: Awaiting HyperPay payment, HyperPay payment authorized und HyperPay payment on hold. PrestaShop verknüpft ein neues Zahlungsmodul mit den Währungen, Ländern und Kundengruppen, die in diesem Moment aktiv sind. Länder, die Sie später aktivieren, müssen unter Payment > Preferences erlaubt werden.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Test mode is on: payments go to the HyperPay test system and no real money is charged., solange der Testmodus aktiv ist. Sie wird gewarnt, wenn das Access Token oder die Entity ID des aktuellen Modus fehlt (die Zahlungsart wird dann im Bestellvorgang 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). Beim Speichern werden Leerzeichen aus den Zugangsdaten entfernt, und die Seite warnt, wenn ein Webhook-Schlüssel kein 64-stelliger hexadezimaler Schlüssel ist.

HyperPay

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

Title: der Titel, den der Kunde im Bestellvorgang sieht. Er ist zugleich der Name der Zahlungsart, der in der Bestellung gespeichert wird. Standard: Credit/Debit Card (HyperPay). Pflichtfeld.

Description: die Beschreibung, die der Kunde im Bestellvorgang 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: verwendet das Test-System von HyperPay (eu-test.oppwa.com) und die Testzugangsdaten. Es wird kein echtes Geld abgebucht. Deaktivieren Sie den Modus, um echte Zahlungen mit den Live-Zugangsdaten (eu-prod.oppwa.com) anzunehmen. Standard: aktiv. Solange er aktiv ist, sehen die Kunden Test mode: no real payment will be made. unter der Zahlungsart.

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 zur Entschlüsselung der Webhook-Benachrichtigungen des Test-Systems.

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

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

Live Webhook Key: der 64-stellige hexadezimale Schlüssel zur Entschlüsselung der Webhook-Benachrichtigungen des Live-Systems.

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.

Gespeicherte Geheimnisse löschen: aktivieren Sie ein Token oder einen Schlüssel und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.

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. Mit suchmaschinenfreundlichen URLs sieht sie etwa so aus: https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Kopieren Sie danach 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 mit Ihren Schlüsseln nicht entschlüsselt werden kann, wird abgelehnt. Verarbeitet werden nur Zahlungsbenachrichtigungen, und die Zahlung muss zu einer Zahlungssitzung eines Ihrer Warenkörbe 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 auch Erfassungen, Rückbuchungen, Erstattungen und Chargebacks, die im HyperPay-Dashboard vorgenommen werden (siehe Bestellungen und Erstattungen). Ohne Webhook wird eine Zahlung nur bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

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 freigeschaltet hat; mada, STC Pay und Apple Pay verwenden oft eine eigene Entität, die dieses Modul nicht unterstützt.

Advanced

Enable Logging: protokolliert API-Anfragen und -Antworten in logs/hyperpay_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. 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: wenn aktiviert, entfernt die Deinstallation des Moduls die Einstellungen, die Tabelle der HyperPay-Zahlungsversuche und die Protokolldateien. Bestellungen und die Bestellstatus des Moduls bleiben erhalten. Standard: aus.

Bestellvorgang

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit/Debit Card (HyperPay)) und bestätigt die Bestellung. Das Modul bereitet für den Warenkorbbetrag in der Warenkorbwährung eine HyperPay-Zahlungssitzung vor und öffnet die Seite HyperPay payment Ihres Shops mit dem HyperPay-Widget und dem Hinweis 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 wählt Choose another payment method, um zum Bestellvorgang zurückzukehren. An diesem Punkt gibt es noch keine Bestellung. Wird die Seite neu geladen, wird dieselbe Zahlungssitzung bis zu 25 Minuten lang wiederverwendet, solange sich der Warenkorb nicht ändert.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Das Modul prüft, ob die Zahlung zu einer Zahlungssitzung dieses Warenkorbs gehört, und fragt das Ergebnis per serverseitiger Anfrage bei HyperPay ab, und zwar im Modus, in dem die Zahlungssitzung erstellt wurde. 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 dem Warenkorb übereinstimmen. Treffen Rücksprung und Webhook gleichzeitig ein, werden sie nacheinander verarbeitet, sodass die Bestellung nie doppelt angelegt wird. Nach der Bestätigung der Zahlung wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite.

Ist die Zahlung nicht erfolgreich verlaufen, kehrt der Kunde mit einer Meldung in den Bestellvorgang 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; jeder neue Versuch erhält eine neue HyperPay-Zahlungssitzung. Kann das Zahlungsformular nicht vorbereitet werden, bleibt der Kunde im Bestellvorgang mit einer kurzen Meldung, etwa dass einige Rechnungsdaten vom Zahlungsanbieter nicht akzeptiert wurden oder dass das Zahlungsformular wegen eines Konfigurationsfehlers nicht verfügbar ist. Der technische Grund wird im Protokoll festgehalten.

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

Der Webhook funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Das Modul bietet keine Erstattungen oder Stornierungen aus PrestaShop, 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

No order yet: der Kunde wurde zur Zahlungsseite geschickt und hat nicht bezahlt, die Zahlung wurde abgelehnt oder HyperPay hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted: eine Sofortbelastung wurde bestätigt oder eine Vorautorisierung wurde erfasst. Die Zahlung wird mit der HyperPay-Zahlungs-ID als Transaktions-ID erfasst, und eine interne Notiz zeigt den HyperPay-Ergebniscode, die Beschreibung und die Zahlungs-ID. Hat HyperPay die Zahlung zur manuellen Prüfung markiert, weist die Notiz darauf hin; prüfen Sie sie vor dem Versand im HyperPay-Dashboard.

HyperPay payment authorized: der Betrag wurde durch eine Vorautorisierung reserviert. Erfassen Sie ihn im HyperPay-Block der Bestellung oder im HyperPay-Dashboard; der Erfassungs-Webhook setzt die Bestellung danach auf Payment accepted.

Awaiting HyperPay payment: HyperPay hat die Zahlung als ausstehend gemeldet. Die Bestellung wechselt zu Payment accepted, sobald HyperPay die Zahlung bestätigt.

HyperPay payment on hold: HyperPay meldete einen anderen Betrag oder eine andere Währung als im Warenkorb oder in der Bestellung (zum Beispiel wurde der Warenkorb geändert, nachdem die Zahlungsseite geöffnet wurde), oder die Zahlung kam an, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Zahlung im HyperPay-Dashboard und bearbeiten Sie danach die Bestellung oder erstatten Sie die Zahlung.

Canceled: eine Vorautorisierung wurde im HyperPay-Dashboard storniert, und der Storno-Webhook bricht die autorisierte Bestellung ab.

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

HyperPay-Zahlungsblock

Die Bestellseite zeigt einen Block HyperPay payment mit der Zahlungs-ID (und der Erfassungs-ID nach einer Erfassung), dem Transaktionstyp, der Sitzungs-ID, der Händler-Transaktions-ID, dem an HyperPay gesendeten Betrag, dem Ergebnis und einem Hinweis Test mode für Testzahlungen. Die Notizen des Moduls befinden sich in den internen Nachrichten der Bestellung.

Erfassung

Bei einer Bestellung im Status HyperPay payment authorized zeigt der Block Capture payment mit dem Betrag. Klicken Sie darauf und bestätigen Sie Capture the pre-authorized amount through HyperPay?. Erfasst wird die aktuelle Bestellsumme im Modus, in dem die Vorautorisierung erfolgte; daher müssen Access Token und Entity ID dieses Modus eingerichtet sein. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Nach einer erfolgreichen Erfassung wechselt die Bestellung zu Payment accepted, und die Erfassungs-ID wird der Zahlung und den Notizen hinzugefügt. 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 Stornieren (Void) einer Vorautorisierung erfolgt im HyperPay-Dashboard.

Erstattungen

Erstattungen aus PrestaShop werden nicht unterstützt, und die Standard-Erstattungsschaltflächen von PrestaShop senden kein Geld über HyperPay zurück. Erstatten Sie die Zahlung im HyperPay-Dashboard und erfassen Sie sie bei Bedarf in PrestaShop als Teilerstattung oder Gutschrift. Erstattungen und Chargebacks, die bei HyperPay vorgenommen werden, werden vom Webhook als Notiz zur Bestellung hinzugefügt; der Bestellstatus ändert sich nicht.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox HyperPay Payment Gateway ist der erste Block unter Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-hyperpay und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nach einer Änderung der Shop-Adresse oder nachdem Sie einen Domain-Platz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Einrichtung. 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 im Bestellvorgang nicht angezeigt. Versucht dennoch jemand eine Zahlung, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Shop weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht im Bestellvorgang testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt, und Erfassungen und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support benötigen eine Verlängerung. Der Status wird während Ihrer Arbeit im Back Office automatisch erneut geprüft: 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 oder Zurücksetzen des Moduls werden der Lizenzschlüssel und der Lizenzstatus immer entfernt.

Fehlerbehebung

HyperPay erscheint nicht im Bestellvorgang: 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 Testdaten im Testmodus, die Livedaten im Livemodus. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung war erfolgreich, aber es wurde keine Bestellung angelegt: 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 genutzten Modus existiert, ob seine URL genau der unter Webhook URL angezeigten entspricht und ob sein Entschlüsselungsschlüssel im Feld für den Webhook-Schlüssel desselben Modus steht. Aktivieren Sie Enable Logging und sehen Sie sich das Feld Log auf der Modulseite 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 die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). HyperPay wiederholt den Webhook. Der Grund steht im Protokoll.

Das Protokoll zeigt Webhook ignored: die Zahlung gehört nicht zu einem Warenkorb 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: sehen Sie im Protokoll nach. 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 freigeschaltet sind.

Bestellung ist HyperPay payment on hold: lesen Sie die Notizen der Bestellung (siehe Bestellstatus), prüfen Sie die Zahlung im HyperPay-Dashboard und bearbeiten Sie danach die Bestellung oder erstatten Sie die Zahlung.

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

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox HyperPay Payment Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall aktiviert, werden die Einstellungen, die Tabelle der HyperPay-Zahlungsversuche und die Protokolldateien entfernt. Ist es deaktiviert, bleibt alles für eine spätere Neuinstallation erhalten. Die Bestellstatus Awaiting HyperPay payment, HyperPay payment authorized und HyperPay payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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