VibeFox Eupago for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Währung: Euro (EUR). Eupago rechnet nur in Euro ab; bei Warenkörben in anderen Währungen wird die Zahlungsmethode an der Kasse deshalb ausgeblendet.

Eupago-Konto: Sie benötigen den API-Schlüssel Ihres Eupago-Kanals und den Schlüssel eines Webhook 2.0, den Sie im Eupago-Backoffice anlegen (siehe Konfiguration). Das Live-Backoffice ist clientes.eupago.pt, das Sandbox-Backoffice ist sandbox.eupago.pt. Sandbox und Live sind getrennte Konten mit getrennten Schlüsseln.

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel funktioniert 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 aus.

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

3. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie den API-Schlüssel Ihres Eupago-Kanals ein, erstellen Sie im Eupago-Backoffice einen Webhook 2.0 und fügen Sie dessen Schlüssel ein (siehe Konfiguration).

5. Wählen Sie die Payment Method, aktivieren Sie Enable/Disable und klicken Sie auf Save. Legen Sie im Sandbox-Modus eine Testbestellung an und deaktivieren Sie danach Sandbox Mode.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Eupago payment und Eupago payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken; der Euro muss für das Modul erlaubt bleiben.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Eupago Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Ist die Zahlungsmethode aktiviert, warnt Sie die Seite oberhalb der Felder, wenn der API-Schlüssel des aktuellen Modus leer ist (die Zahlungsmethode wird dann an der Kasse ausgeblendet), oder sie zeigt Sandbox mode: no real payments are taken., solange der Sandbox-Modus aktiv ist.

Eupago

Enable/Disable: Enable Eupago Gateway schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Eupago. Pflichtfeld: Ein leerer Titel führt zu Enter a title for the payment method.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via Eupago.

Payment Method: die eine Eupago-Methode, die an der Kasse angeboten wird.

Order Status After Payment: der Bestellstatus, der gesetzt wird, sobald die Zahlung bestätigt ist.

Eupago-Konto

Holen Sie den API-Schlüssel Ihres Kanals und den Schlüssel des Webhook 2.0 im Eupago-Backoffice: clientes.eupago.pt (Live) oder sandbox.eupago.pt (Sandbox). Sandbox und Live sind getrennte Konten mit getrennten Schlüsseln.

Sandbox Mode: verwendet sandbox.eupago.pt und die Sandbox-Schlüssel. Es werden keine echten Zahlungen abgebucht. Standard: an. Schalten Sie es aus, um mit den Live-Schlüsseln echte Zahlungen zu erhalten. Solange es aktiv ist, sehen Kunden SANDBOX / TEST MODE unter der Zahlungsmethode.

Live API Key: der API-Schlüssel Ihres Live-Kanals von Eupago (clientes.eupago.pt).

Live Webhook Key: der Verschlüsselungsschlüssel Ihres Live-Webhook 2.0. Pflichtfeld: Benachrichtigungen ohne gültige Signatur werden abgelehnt.

Sandbox API Key: der API-Schlüssel Ihres Sandbox-Kanals (sandbox.eupago.pt).

Sandbox Webhook Key: der Verschlüsselungsschlüssel Ihres Sandbox-Webhook 2.0.

Gespeicherte 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.

Clear saved keys: Setzen Sie ein Häkchen bei einem Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Webhook-URL

Der Webhook teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist. Erstellen Sie im Eupago-Backoffice einen Webhook 2.0 mit der URL, die in diesem Abschnitt angezeigt wird, mit der Methode POST und aktivierter Verschlüsselung. Mit freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_eupago_gateway/webhook, eventuell mit einem Sprachcode wie /pt/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Erstellen Sie einen Webhook im Sandbox-Backoffice und einen weiteren im Live-Backoffice.

Kopieren Sie den Schlüssel jedes Webhooks in Sandbox Webhook Key bzw. Live Webhook Key. Webhooks ohne gültige Signatur werden abgelehnt. Ein unverschlüsselter Webhook wird nur akzeptiert, wenn Eupago ihn signiert; deshalb lassen Sie die Verschlüsselung aktiviert. Eine Benachrichtigung muss mit dem Schlüssel des Modus signiert sein, in dem die Zahlung gestartet wurde, daher bezahlt eine Sandbox-Benachrichtigung nie eine Live-Zahlung. Das Modul reagiert auf diese Benachrichtigungsstatus:

Andere Status erfordern keine Maßnahme. Der alte GET-Callback von Eupago an dieselbe URL wird ebenfalls akzeptiert; er wird über den API-Schlüssel authentifiziert und meldet immer eine Zahlung. Ohne Benachrichtigungen werden Bestellungen nie als bezahlt markiert: Das Modul fragt Eupago nicht ab, und die Rückkehr des Kunden bezahlt keine Bestellung. Der Webhook funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Erweitert

Debug Log: schreibt API-Aufrufe und Benachrichtigungen in logs/eupago_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Schlüssel, E-Mail-Adressen und vollständige Telefonnummern werden nicht protokolliert. Fehler werden immer protokolliert. 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 Gateway-Einstellungen, die Eupago-Zahlungsdatensätze dieses Moduls und das Protokoll. Bestellungen und ihre Zahlungsdaten bleiben erhalten. Standard: aus.

Kasse

Der Kunde wählt im Zahlungsschritt die Zahlungsmethode (standardmäßig Eupago) und gibt die Bestellung auf. Was danach geschieht, hängt von der Payment Method ab.

Multibanco: An der Kasse sieht der Kunde You will receive Multibanco payment details after placing the order. Das Modul erstellt eine Multibanco-Referenz für die Warenkorbsumme. Die Bestellung wird sofort als Awaiting Eupago payment angelegt, wie jede PrestaShop-Bestellung, und der Warenkorb wird geleert. Die Bestellbestätigungsseite zeigt Multibanco Payment Details mit Entität, Referenz und Betrag. Dieselben Angaben werden der Zahlungszeile der Bestellbestätigungs-E-Mail hinzugefügt. Der Kunde bezahlt am Geldautomaten oder im Online-Banking.

MB WAY: An der Kasse gibt der Kunde MB WAY Phone Number ein, vorausgefüllt mit der Telefonnummer der Rechnungsadresse. Portugiesische Nummern können ohne +351 eingegeben werden. Eine falsche Nummer führt zu Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). Das Modul sendet die Zahlungsanfrage an die MB-WAY-App und legt die Bestellung als Awaiting Eupago payment an. Die Bestellbestätigungsseite fordert den Kunden auf, die MB-WAY-App auf der maskierten Telefonnummer zu öffnen und die Anfrage innerhalb von 5 Minuten zu bestätigen.

Credit Card: An der Kasse sieht der Kunde You will be redirected to a secure payment page to enter your card details. Der Kunde wird auf die Kartenseite von Eupago weitergeleitet, je nach Sprache des Warenkorbs auf Portugiesisch, Spanisch oder Englisch. Es existiert noch keine Bestellung, und der Warenkorb bleibt erhalten. Die Bestellung wird erst angelegt, wenn Eupago die Zahlung bestätigt. Ist die Benachrichtigung eingetroffen, wenn der Kunde zurückkehrt, sieht er die übliche Bestellbestätigungsseite. Andernfalls zeigt eine Seite Payment confirmation an: Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. mit einer Schaltfläche Check again. Schlägt die Kartenzahlung fehl oder wird sie abgebrochen, kehrt der Kunde zur Kasse zurück, mit The card payment was not completed. You can try again or choose another payment method. oder The card payment was cancelled. You can try again or choose another payment method.

Bei jeder Methode wird die Bestellung erst dann als bezahlt markiert, wenn Eupago die Zahlung mit einer verifizierten Benachrichtigung bestätigt. Die Zahlungsdetails werden nur angezeigt, solange die Bestellung Awaiting Eupago payment ist. Meldet Eupago später, dass die Zahlung storniert, abgelaufen oder fehlgeschlagen ist und die Bestellung nicht bezahlt wurde, zeigt die Bestellbestätigungsseite Your Eupago payment was not completed. Please contact us about this order.

Kann Eupago die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. Es wird keine Bestellung angelegt, und die Details stehen im Protokoll. Ein Warenkorb in einer anderen Währung führt zu Eupago only supports payments in EUR.

Das Modul bietet pro Installation eine Eupago-Methode an. Es gibt keine Erstattungen aus PrestaShop, keine gespeicherten Karten, Abonnements oder Vorautorisierungen, kein PayShop, Cofidis Pay, Bizum oder andere Eupago-Methoden, keine SMS-Erinnerungen, kein Ablaufdatum für Multibanco und keine Statusabfrage.

Bestellungen

Bestellstatus

No order yet: Eine Kartenzahlung wurde gestartet, und Eupago hat sie noch nicht bestätigt. Es existiert nur der Warenkorb.

Awaiting Eupago payment: Eine Multibanco-Referenz oder eine MB-WAY-Anfrage wurde erstellt. Die Notiz zeigt die Entität und die Referenz bzw. die maskierte Telefonnummer.

Payment accepted or Delivered: Die Zahlung wurde bestätigt. Der Status folgt der Order Status After Payment. Die Zahlung wird mit der Eupago-Transaktions-ID als Transaktions-ID erfasst, und eine Notiz zeigt Methode, Transaktions-ID und Referenz.

Eupago payment on hold: Eupago hat eine Zahlung mit abweichendem Betrag oder abweichender Währung gemeldet, mit einer Referenz, die nicht für diesen Warenkorb erstellt wurde, oder für eine Bestellung, die inzwischen storniert wurde oder fehlgeschlagen ist (zum Beispiel eine verspätet bezahlte Multibanco-Referenz). Die Notiz erklärt dies. Prüfen Sie die Zahlung und den Lagerbestand und vervollständigen Sie die Bestellung dann manuell oder erstatten Sie dem Kunden den Betrag. Spätere Benachrichtigungen zu dieser Zahlung schließen die Bestellung nicht ohne Ihr Zutun ab.

Canceled: Eupago hat die Zahlung für den aktuellen Zahlungsversuch einer wartenden Bestellung als storniert oder abgelaufen gemeldet.

Payment error: Eupago hat einen Fehler für den aktuellen Zahlungsversuch einer wartenden Bestellung gemeldet.

Meldet Eupago eine weitere Zahlung für eine bereits bezahlte Bestellung (zum Beispiel wurde auch eine ältere Multibanco-Referenz bezahlt), bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, eine doppelte Zahlung zu prüfen und sie im Eupago-Backoffice zu erstatten. Eine Benachrichtigung über eine Zahlung öffnet nie eine Bestellung wieder, die bezahlt und später storniert oder erstattet wurde.

Eupago-Zahlungsblock

Die Bestellseite zeigt einen Block Eupago payment mit jedem Zahlungsversuch des Warenkorbs: Datum, Methode, ein Abzeichen Sandbox für Sandbox-Zahlungen, Betrag, die Multibanco-Entität und -Referenz bzw. die maskierte MB-WAY-Telefonnummer, die Eupago-Transaktions-ID und den Status. Solange die Bestellung Eupago payment on hold ist, zeigt der Block eine Warnung Manual review. Darunter listet Eupago notes die Notizen des Moduls zur Bestellung auf, die neuesten zuerst.

Erstattungen

Erstattungen aus PrestaShop werden nicht unterstützt. Erstatten Sie dem Kunden den Betrag im Eupago-Backoffice und aktualisieren Sie die Bestellung in PrestaShop manuell. Die standardmäßigen Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden über Eupago kein Geld zurück.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Eupago Gateway ist der erste Block auf Modules > Module Manager > VibeFox Eupago 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, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: presta-payment-eupago 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. Nachdem sich die Adresse des Shops geändert hat oder Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Einrichtung. Wenn Sie den Schlüssel aus dem Shop entfernen, wird sein Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Eupago Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Storefront weiß nicht, dass Sie im Back-Office angemeldet sind, daher wird die Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen aber eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back-Office arbeiten: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Eupago erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der API-Schlüssel des aktuellen Modus gesetzt ist (Sandbox API Key im Sandbox-Modus, Live API Key im Live-Modus). Die Warenkorbwährung muss EUR sein, und unter Payment > Preferences muss das Modul für den Euro, das Land des Kunden und die Kundengruppe erlaubt sein. Bei Multibanco muss die Bestellsumme zwischen 1 € und 999 999,99 € liegen.

Die Zahlung ist eingegangen, aber die Bestellung bleibt bei Awaiting Eupago payment oder es wurde keine Bestellung angelegt: Die Benachrichtigung von Eupago kommt nicht an oder wird abgelehnt. Prüfen Sie im Eupago-Backoffice des verwendeten Modus, ob der Webhook 2.0 existiert, ob seine URL genau der unter Webhook URL angezeigten entspricht, ob die Methode POST ist und die Verschlüsselung aktiv ist. Prüfen Sie, ob sein Schlüssel im passenden Feld steht (Sandbox Webhook Key oder Live Webhook Key). Aktivieren Sie Debug Log und sehen Sie sich das Feld Log auf der Modulseite an. Kommt eine Benachrichtigung nie an, prüfen Sie die Zahlung im Eupago-Backoffice.

Der Webhook antwortet Invalid signature oder Missing signature: Der Webhook-Schlüssel im Modul stimmt nicht mit dem Schlüssel des Webhooks überein, oder der Webhook ist unverschlüsselt und unsigniert. Kopieren Sie den Schlüssel erneut und lassen Sie die Verschlüsselung aktiv.

Der Webhook antwortet Webhook key not configured: Es ist kein Webhook-Schlüssel gesetzt. Eupago wiederholt die Benachrichtigung, nachdem Sie den Schlüssel eingefügt haben.

Der Webhook antwortet Decryption failed: Die Signatur ist gültig, aber der Inhalt konnte nicht entschlüsselt werden. Prüfen Sie die Einstellungen des Webhook 2.0 im Eupago-Backoffice.

Der Webhook antwortet Environment mismatch: Die Benachrichtigung ist mit dem Schlüssel des anderen Modus signiert als dem, in dem die Zahlung gestartet wurde. Eine Sandbox-Benachrichtigung bezahlt nie eine Live-Zahlung und umgekehrt. Prüfen Sie, ob die Sandbox- und Live-Schlüssel nicht vertauscht sind.

Der Webhook antwortet Order not found: Die Benachrichtigung bezieht sich auf einen Warenkorb ohne Eupago-Zahlung dieses Shops, zum Beispiel eine Zahlung aus einem anderen Shop mit demselben Eupago-Kanal.

Der Webhook antwortet Busy or Retry: Der Warenkorb wurde im selben Moment von einer anderen Anfrage verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Eupago wiederholt die Benachrichtigung. Der Grund steht im Protokoll.

Der alte Callback antwortet Invalid API key: Der von Eupago gesendete API-Schlüssel stimmt nicht mit Live API Key oder Sandbox API Key überein. Dieselbe Antwort erscheint, wenn Sie die Webhook-URL im Browser öffnen; das ist normal.

Der Kunde sieht The MB WAY payment could not be started: Prüfen Sie, ob die Telefonnummer mit MB WAY verknüpft ist, und versuchen Sie es erneut.

Die Bestellung ist nach der Zahlung Eupago payment on hold: Lesen Sie die Eupago notes im Block Eupago payment. Betrag oder Währung wichen ab, die Referenz war unbekannt, oder die Zahlung kam, nachdem die Bestellung storniert wurde. Prüfen Sie die Zahlung im Eupago-Backoffice und vervollständigen Sie dann die Bestellung oder erstatten Sie dem Kunden den Betrag.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Eupago 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 Gateway-Einstellungen, die Eupago-Zahlungsdatensätze dieses Moduls und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen und Datensätze für eine spätere Neuinstallation erhalten. Die Bestellstatus Awaiting Eupago payment und Eupago payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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