VibeFox Adyen 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.

Adyen-Konto: Sie benötigen den Namen Ihres Adyen-Händlerkontos, einen API-Schlüssel und einen HMAC-Schlüssel für jede verwendete Umgebung (Test und Live) und für Live-Zahlungen das Live-URL-Präfix. Der API-Schlüssel gehört zu einem API-Credential mit den Rollen Checkout webservice und Merchant PAL webservice. Der HMAC-Schlüssel wird für den Standard-Webhook erzeugt (siehe Konfiguration). Der Test-Kundenbereich ist ca-test.adyen.com, der Live-Kundenbereich ist ca-live.adyen.com. Test- und Live-Schlüssel sind getrennt. Ein Client-Schlüssel wird nicht benötigt, da die Zahlungsseite von Adyen gehostet wird.

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 später in der Modulliste nach VibeFox Adyen Gateway und klicken Sie dort auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Konfigurationsseite des Moduls ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie Ihr Händlerkonto, den Test-API-Schlüssel und den Test-HMAC-Schlüssel ein und später den Live-API-Schlüssel, den Live-HMAC-Schlüssel und das Live-URL-Präfix.

5. Fügen Sie im Adyen-Kundenbereich (Test und Live) einen Standard-Webhook mit der URL hinzu, die im Abschnitt Webhook des Moduls angezeigt wird (siehe Konfiguration).

6. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung bei eingeschaltetem Test mode und schalten Sie ihn danach wieder aus.

Bei der Installation legt das Modul den Bestellstatus Adyen payment on hold an. PrestaShop bietet ein neues Zahlungsmodul für die Währungen, Länder und Kundengruppen, die zu diesem Zeitpunkt aktiv sind. Prüfen und ändern Sie sie unter Payment > Preferences; Länder, die Sie später hinzufügen, müssen dort ebenfalls angehakt werden.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Adyen Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Solange die Einstellungen des aktuellen Modus unvollständig sind, zeigt die Seite Adyen is hidden at checkout until the test settings are complete (bzw. die Live-Einstellungen) und listet auf, was fehlt: Merchant account, der API-Schlüssel, der HMAC-Schlüssel und im Live-Modus Live URL prefix. Solange der Test-Modus eingeschaltet ist, zeigt die Seite Test mode is on: payment links and refunds go to the Adyen test environment, no real money. Beim Speichern werden ein HMAC-Schlüssel, der nicht hexadezimal ist, und ein Live-URL-Präfix mit anderen Zeichen als Buchstaben, Ziffern und Bindestrichen nicht gespeichert: Eine Warnung nennt das Feld, und der vorherige Wert bleibt erhalten.

Adyen

Enable/Disable: Enable Adyen payment gateway schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden im Bestellvorgang sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Adyen. Pflichtfeld.

Description: der Text, der im Bestellvorgang unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via Adyen.

Adyen-Konto

API-Schlüssel werden im Adyen-Kundenbereich unter Developers > API credentials erstellt. Tragen Sie beide Schlüsselsätze ein; der Schalter Test mode legt fest, welcher verwendet wird.

Test mode: nutzt die Adyen-Testumgebung (kein echtes Geld). Ist er eingeschaltet, gehen Zahlungslinks und Erstattungen an checkout-test.adyen.com mit dem Test-API-Schlüssel. Standard: an. Schalten Sie ihn aus, um echte Zahlungen anzunehmen. Solange er eingeschaltet ist, sehen Kunden unter der Zahlungsmethode Test mode: no real payment is taken.

Merchant account: der Name Ihres Adyen-Händlerkontos (nicht des Firmenkontos), zum Beispiel MyShopECOM. Er ist im Test- und im Live-Kundenbereich in der Regel gleich.

Testzugangsdaten

Wird verwendet, solange Test mode aktiviert ist.

Test API key: aus dem Test-Kundenbereich: Developers > API credentials > Ihr Credential > API key.

Test HMAC key: aus dem Test-Kundenbereich: Developers > Webhooks > Ihr Standard-Webhook > HMAC key (hexadezimal). Pflicht: Webhooks ohne gültige Signatur werden abgelehnt.

Live-Zugangsdaten

Wird verwendet, wenn Test mode deaktiviert ist.

Live API key: aus dem Live-Kundenbereich: Developers > API credentials > Ihr Credential > API key.

Live HMAC key: aus dem Live-Kundenbereich: Developers > Webhooks > Ihr Standard-Webhook > HMAC key (hexadezimal).

Live URL prefix: aus dem Live-Kundenbereich: Developers > API URLs, zum Beispiel 1797a841fbb37ca7-AdyenDemo aus https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Sie können die ganze URL einfügen; das Präfix wird beim Speichern daraus übernommen.

Gespeicherte API-Schlüssel und HMAC-Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer, und sein Hinweis endet mit Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved secrets: setzen Sie einen Haken bei einem Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Webhook

Bestellungen werden nur durch Adyen-Webhooks angelegt. Gehen Sie im Kundenbereich (Test und Live) zu Developers > Webhooks und fügen Sie einen Standard webhook mit der URL hinzu, die unter Webhook URL in diesem Abschnitt angezeigt wird. Bei aktivierten Friendly URLs sieht sie so aus: https://your-shop/module/wcp_adyen_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen, denn Adyen folgt keinen Weiterleitungen. Wählen Sie das Format JSON, aktivieren Sie Generate HMAC key und kopieren Sie den Schlüssel in Test HMAC key oder Live HMAC key.

Die Umgebung jeder Benachrichtigung bestimmt den HMAC-Schlüssel, und eine Benachrichtigung wird nur auf einen Zahlungslink angewendet, der in derselben Umgebung und mit demselben Händlerkonto erstellt wurde. Eine Testbenachrichtigung bestätigt nie eine Live-Zahlung. Webhooks ohne gültige Signatur werden mit HTTP 401 abgelehnt, und Adyen wiederholt die Zustellung später. Ohne Webhook wird keine Bestellung angelegt.

Das Modul verarbeitet folgende Ereignisse:

Andere Ereignisse werden den Bestellnotizen hinzugefügt. Benachrichtigungen, die nicht zu einem Warenkorb dieses Shops gehören, zum Beispiel die Testschaltfläche im Kundenbereich, werden angenommen und ignoriert. Der Webhook funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Erweitert

Order status after payment: der Bestellstatus, der durch einen erfolgreichen AUTHORISATION-Webhook gesetzt wird.

Abweichungen bei Betrag oder Währung und fehlgeschlagene Erfassungen gehen immer in Adyen payment on hold über.

Debug log: schreibt API-Aufrufe und Webhook-Ereignisse in logs/adyg_debug.log.php im Modulordner. Die Datei kann nicht im Browser geöffnet werden. Fehler werden immer protokolliert, auch wenn der Schalter aus ist. Protokolle enthalten nie API- oder HMAC-Schlüssel oder personenbezogene Daten der Käufer. 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 des Moduls die Moduleinstellungen, die Adyen-Zahlungsdatensätze (PSP-Referenzen, Webhook-Ereignisse, Erstattungen) und die Protokolle. Der Bestellstatus Adyen payment on hold und die Bestellungen bleiben erhalten. Standard: aus.

Bestellvorgang

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Adyen) und sieht den Hinweis You will be redirected to Adyen to complete the payment securely. Nach der Bestätigung erstellt das Modul einen Adyen-Zahlungslink für den Warenkorbbetrag in der Warenkorbwährung und leitet den Kunden zur Zahlungsseite von Adyen weiter. Dort bezahlt er mit jeder Methode, die in Ihrem Adyen-Konto aktiviert ist. E-Mail-Adresse, Name und Rechnungsland des Kunden sowie die Shopsprache werden an Adyen übergeben, und die Zahlung erscheint als Cart # mit der Warenkorbnummer. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Rückkehr selbst legt keine Bestellung an und bezahlt keine: Die Bestellung wird erst als bezahlt markiert, wenn Adyen dies mit dem signierten AUTHORISATION-Webhook bestätigt und Betrag und Währung mit dem Warenkorb übereinstimmen. Ist der Webhook bereits eingegangen, sieht der Kunde die übliche Bestellbestätigungsseite mit Your payment with Adyen has been received. (oder Your payment with Adyen has been received and is being reviewed by the store. bei einer zur Prüfung zurückgehaltenen Bestellung). Hat Adyen die Zahlung vorher storniert, zeigt die Seite Your Adyen payment was not completed. Please contact us about this order. Ist der Webhook noch nicht eingegangen, zeigt eine Seite Payment confirmation den Text Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. mit den Schaltflächen Check again und Back to checkout, für einen Kunden, der die Zahlung nicht abgeschlossen hat.

Wird die Zahlung abgelehnt, wird keine Bestellung angelegt, und der Kunde kann es erneut versuchen. Startet der Kunde eine neue Zahlung für denselben Warenkorb, läuft der vorherige Zahlungslink ab, sodass er nicht mehr bezahlt werden kann. Hat der Warenkorb bereits eine Bestellung, wird der Kunde zu deren Bestätigung geleitet statt zu einer neuen Zahlung.

Kann der Zahlungslink nicht erstellt werden, bleibt der Kunde im Bestellvorgang mit Payment could not be initiated. Please try again or choose another payment method. Der Grund wird im Protokoll festgehalten. Sind die Einstellungen unvollständig, lautet die Meldung Payment gateway is not configured properly. Please contact the store administrator.

Entwickler können die Anfrage für den Zahlungslink mit dem Hook actionAdygPaymentLinkRequest anpassen.

Das Modul bietet keine Abonnements oder wiederkehrenden Zahlungen, keine gespeicherten Karten, keine Kartenfelder auf der Website (Drop-in oder Components), keine Schaltflächen für Erfassung oder Stornierung in PrestaShop und keine Basis-Authentifizierung für Webhooks.

Bestellungen und Erstattungen

Bestellstatus

No order yet: der Kunde wurde zu Adyen weitergeleitet und hat nicht bezahlt, die Zahlung wurde abgelehnt oder Adyen hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted, Delivered or Adyen payment on hold: die Zahlung wurde autorisiert. Der Status richtet sich nach Order status after payment. Die Zahlung wird mit der PSP-Referenz von Adyen als Transaktions-ID erfasst, und eine Notiz zeigt Betrag, PSP-Referenz und Zahlungsmethode.

Adyen payment on hold after payment: Adyen hat einen anderen Betrag oder eine andere Währung als den Warenkorbbetrag bestätigt (zum Beispiel wurde der Warenkorb geändert, nachdem die Zahlung begonnen hatte), eine Erfassung ist fehlgeschlagen oder die Zahlung kam, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Zahlung im Kundenbereich und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Canceled: die Zahlung dieser Bestellung wurde in Adyen storniert.

Refunded: die Zahlung wurde über das Modul vollständig erstattet.

Trifft eine zweite erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein, etwa über einen alten Zahlungslink, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, im Kundenbereich nach einer doppelten Belastung zu suchen und sie dort bei Bedarf zu erstatten.

Adyen-Zahlungsblock

Die Bestellseite zeigt einen Block Adyen payment mit der PSP-Referenz, dem Zahlungslink, dem Händlerkonto und der Umgebung, dem Zahlungsstatus, dem bezahlten und erstatteten Betrag, einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf und den Adyen notes: den Notizen, die das Modul zur Bestellung hinzufügt (Zahlung autorisiert, Betragsabweichung, doppelte Zahlung, Erfassung, Stornierung, Ergebnisse von Erstattungen), neueste zuerst. Diese Notizen sind private Nachrichten der Bestellung; PrestaShop 8.2 und 9 zeigen sie nicht an anderer Stelle der Bestellseite.

Erstattungen

Geben Sie im Block Adyen payment den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Adyen. Bestätigen Sie die Frage Refund this amount through Adyen? This cannot be undone. Voll- und Teilerstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattungen erfolgen im Betrag und in der Währung, die Adyen autorisiert hat. Nach einer Betrags- oder Währungsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht den Bestellbetrag. Die Erstattung wird an die Umgebung und das Händlerkonto gesendet, mit denen die Zahlung erfolgt ist, daher muss der API-Schlüssel dieser Umgebung hinterlegt sein. Lehnt Adyen die Anfrage ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst.

Adyen verarbeitet Erstattungen asynchron: Die Anfrage wird dem Erstattungsverlauf und den Notizen mit dem Status received hinzugefügt, und das endgültige Ergebnis kommt über den Webhook REFUND oder REFUND_FAILED. Eine fehlgeschlagene Erstattung zählt nicht mehr als erstattet. Erreichen die gesendeten Erstattungen den bezahlten Betrag, wird die Bestellung auf Refunded gesetzt. Eine Teilerstattung ändert den Status nicht. Bei manueller Erfassung in Adyen können nur erfasste Zahlungen erstattet werden.

Das Modul erstellt keine Gutschriften. Die üblichen Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Adyen zurück. Erstattungen, die im Adyen-Kundenbereich vorgenommen werden, kommen per Webhook an und werden den Notizen hinzugefügt. Bestellstatus und Gutschriften werden nicht automatisch geändert.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Adyen Gateway ist der erste Block auf Modules > Module Manager > VibeFox Adyen 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 Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv 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-adyen 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 Shopadresse oder nachdem Sie in Ihrem Konto einen Domainplatz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul weiter mit dem zuletzt bekannten Status.

Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch bei einem Multistore-Setup. Wenn Sie den Schlüssel aus dem Shop entfernen, wird der Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Adyen Kunden im Bestellvorgang 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 im Bestellvorgang nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen bleiben unberührt: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

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

Fehlerbehebung

Adyen erscheint nicht im Bestellvorgang: prüfen Sie, dass die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Einstellungen des aktuellen Modus vollständig sind: Merchant account, der API-Schlüssel und der HMAC-Schlüssel dieses Modus und im Live-Modus Live URL prefix. Die Einstellungsseite listet auf, was fehlt. Prüfen Sie unter Payment > Preferences, dass das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: der Webhook funktioniert nicht. Prüfen Sie im Kundenbereich der verwendeten Umgebung (Test oder Live), dass der Standard-Webhook existiert, dass seine URL genau der unter Webhook URL angezeigten entspricht und dass die Methode JSON ist. Prüfen Sie, dass der HMAC-Schlüssel dieses Webhooks im passenden Feld steht (Test HMAC key oder Live HMAC key). Bei einem ungültigen oder fehlenden HMAC-Schlüssel antwortet das Modul mit HTTP 401, und Adyen wiederholt die Zustellung später, sodass die Bestellung automatisch angelegt wird, sobald der Schlüssel korrigiert ist. Das Protokoll zeigt Webhook rejected: invalid HMAC signature oder dass der HMAC-Schlüssel nicht konfiguriert ist.

Der Webhook antwortet [rejected] HMAC key not configured: der HMAC-Schlüssel der Umgebung der Benachrichtigung ist leer. Fügen Sie ihn in die Einstellungen ein.

Der Webhook antwortet [rejected] busy, retry later: der Warenkorb wurde im selben Moment von einer anderen Zustellung verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Adyen wiederholt den Webhook automatisch. Der Grund steht im Protokoll.

Die Webhook-URL zeigt [rejected] POST required in the browser: das ist normal. Die URL nimmt nur Benachrichtigungen von Adyen an.

Die HMAC-Schlüssel-Warnung beim Speichern: das Feld muss den hexadezimalen HMAC-Schlüssel aus dem Kundenbereich enthalten. Der vorherige Wert wurde beibehalten.

Der Kunde sieht Payment could not be initiated: prüfen Sie das Feld Log auf der Modulseite (Fehler werden immer protokolliert). Prüfen Sie den API-Schlüssel, das Händlerkonto und im Live-Modus das Live-URL-Präfix.

Bestellung ist nach der Zahlung Adyen payment on hold: lesen Sie die Notiz zur Bestellung. Der von Adyen bestätigte Betrag oder die Währung stimmte nicht mit dem Warenkorb überein, eine Erfassung ist fehlgeschlagen, oder die Zahlung kam nach einer Stornierung. Es kann auch an der Einstellung Order status after payment liegen.

Erstattung schlägt fehl: die Bestellung braucht eine PSP-Referenz von Adyen, die mit dem AUTHORISATION-Webhook eintrifft. Die Zugangsdaten der Umgebung, in der die Zahlung erfolgte, müssen gesetzt sein; andernfalls zeigt der Block, dass die Zugangsdaten nicht konfiguriert sind. Bei manueller Erfassung können nur erfasste Zahlungen erstattet werden.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Adyen Gateway und wählen Sie Uninstall. Lizenzschlüssel und Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Moduleinstellungen, die Adyen-Zahlungsdatensätze (PSP-Referenzen, Webhook-Ereignisse, Erstattungen) und die Protokolle entfernt. Ist die Option ausgeschaltet, bleiben alle für eine spätere Neuinstallation erhalten, sodass vorher bezahlte Bestellungen weiterhin erstattet werden können. Der Bestellstatus Adyen payment on hold bleibt immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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