VibeFox Adyen for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

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

PHP: 8.0 oder neuer.

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) sowie für Live-Zahlungen das Live-URL-Präfix. Der API-Schlüssel gehört zu API-Anmeldedaten mit den Rollen Checkout webservice und Merchant PAL webservice. Der HMAC-Schlüssel wird für den Standard-Webhook erzeugt (siehe Konfiguration). Die Test-Customer-Area ist ca-test.adyen.com, die Live-Customer-Area ca-live.adyen.com. Test- und Live-Schlüssel sind getrennt.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt für eine 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. Alternativ können Sie den Ordner wcp_adyen_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

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

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

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

6. Fügen Sie in der Customer Area (Test und Live) einen Standard-Webhook mit der URL hinzu, die in den Plugin-Einstellungen angezeigt wird (siehe Konfiguration).

7. Schalten Sie Enable/Disable ein. Testen Sie eine Zahlung bei eingeschaltetem Test mode und entfernen Sie danach das Häkchen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Adyen. Solange die Einstellungen des aktuellen Modus unvollständig sind, zeigt die Seite Adyen is hidden at checkout until the test settings are complete (oder Live-Einstellungen) und listet auf, was fehlt: Merchant account, der API-Schlüssel, der HMAC-Schlüssel und im Live-Modus Live URL prefix. 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 mit einem Fehler abgelehnt; der vorherige Wert bleibt erhalten.

Allgemein

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

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Adyen.

Description: der Text unter der Zahlungsmethode an der Kasse. Standard: Pay securely via Adyen.

Adyen-Konto

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

Test mode: Use the Adyen test environment (no real money). Ist der Schalter eingeschaltet, gehen Zahlungslinks und Erstattungen mit dem Test-API-Schlüssel an checkout-test.adyen.com. Standard: ein. Entfernen Sie das Häkchen, um echte Zahlungen anzunehmen.

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

Testzugangsdaten

Werden verwendet, solange Test mode eingeschaltet ist.

Test API key: aus der Test-Customer-Area: Developers > API credentials > Ihre Zugangsdaten > API key.

Test HMAC key: aus der Test-Customer-Area: Developers > Webhooks > Ihr Standard-Webhook > HMAC key (hexadezimal). Pflichtfeld: Webhooks ohne gültige Signatur werden abgelehnt.

Live-Zugangsdaten

Werden verwendet, wenn Test mode ausgeschaltet ist.

Live API key: aus der Live-Customer-Area: Developers > API credentials > Ihre Zugangsdaten > API key.

Live HMAC key: aus der Live-Customer-Area: Developers > Webhooks > Ihr Standard-Webhook > HMAC key (hexadezimal).

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

Webhook

Bestellungen werden nur durch Adyen-Webhooks als bezahlt markiert. Fügen Sie in der Customer Area (Test und Live) unter Developers > Webhooks einen Standard-Webhook mit der URL hinzu, die in diesem Abschnitt der Einstellungen angezeigt wird. Sie sieht so aus: https://your-site/wc-api/adyg_adyen_webhook/. 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, welcher HMAC-Schlüssel verwendet wird. Webhooks ohne gültige Signatur werden abgelehnt, und Adyen wiederholt sie später. Ohne den Webhook bleiben Bestellungen auf „Zahlung ausstehend“.

Das Plugin verarbeitet diese Ereignisse:

AUTHORISATION: die Zahlung wurde autorisiert (die Bestellung wird nach der Betragsprüfung als bezahlt markiert) oder abgelehnt (eine Bestellung, die auf Zahlung wartet, wird auf „Fehlgeschlagen“ gesetzt).

CAPTURE: die Zahlung wurde erfasst; es wird eine Notiz hinzugefügt.

CAPTURE_FAILED: die Erfassung ist fehlgeschlagen; eine bezahlte Bestellung wird auf Wartend gesetzt.

CANCELLATION: die Zahlung dieser Bestellung wurde in Adyen storniert; die Bestellung wird storniert.

REFUND: eine Erstattung wurde bestätigt oder ist fehlgeschlagen; es wird eine Notiz hinzugefügt.

REFUND_FAILED: eine Erstattung ist fehlgeschlagen; eine Notiz warnt, dass das Geld nicht zurückgezahlt wurde.

Andere Ereignisse werden den Bestellnotizen hinzugefügt. Benachrichtigungen, die nicht zu einer Bestellung dieses Shops gehören, etwa die Testschaltfläche in der Customer Area, werden angenommen und ignoriert.

Erweitert

Order status after payment: der Bestellstatus, der nach einer erfolgreichen Zahlung in einer einzigen Statusänderung gesetzt wird.

Processing: die WooCommerce-Voreinstellung (Standard). Virtuelle, herunterladbare Bestellungen werden automatisch abgeschlossen.

Completed: jede bezahlte Bestellung wird auf Abgeschlossen gesetzt.

On Hold: jede bezahlte Bestellung wartet auf Ihre manuelle Prüfung.

Debug log: Log API calls and webhook events schreibt in WooCommerce > Status > Logs, Quelle wcp_adyen_gateway. Fehler werden immer protokolliert. Das Protokoll enthält nie API- oder HMAC-Schlüssel oder personenbezogene Daten der Käufer. Standard: aus.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Adyen) und gibt die Bestellung auf. Das Plugin erstellt für den Bestellbetrag in der Bestellwährung einen Adyen-Zahlungslink und leitet den Kunden zur Zahlungsseite von Adyen weiter. Dort bezahlt er mit jeder Methode, die in Ihrem Adyen-Konto aktiviert ist. Rechnungs-E-Mail-Adresse, Name und Land des Kunden sowie die Shop-Sprache werden an Adyen übergeben, und die Zahlung erscheint als Order # mit der Bestellnummer.

Nach der Zahlung kehrt der Kunde zur Seite „Bestellung eingegangen“ Ihres Shops zurück. Die Rückkehr selbst markiert die Bestellung nicht als bezahlt: Das geschieht erst, wenn Adyen sie mit dem signierten AUTHORISATION-Webhook bestätigt und Betrag und Währung zur Bestellung passen.

Wird die Zahlung abgelehnt, wird die Bestellung auf „Fehlgeschlagen“ gesetzt, und der Kunde kann es erneut versuchen. Startet der Kunde eine neue Zahlung für dieselbe Bestellung, etwa über die Seite Pay for order, läuft der vorherige Zahlungslink ab, sodass er nicht ebenfalls bezahlt werden kann.

Kann der Zahlungslink nicht erstellt werden, sieht der Kunde Payment could not be initiated. Please try again or choose another payment method. Der Grund wird den Bestellnotizen hinzugefügt. Sind die Einstellungen unvollständig, sieht der Kunde Payment gateway is not configured properly. Please contact the store administrator.

Bei Währungen ohne Dezimalstellen, wie JPY, KRW, IDR oder VND, setzen Sie WooCommerce > Settings > General > Number of decimals auf 0. Andernfalls wird der Gesamtbetrag auf eine ganze Einheit gerundet.

Die Zahlungsmethode funktioniert an der klassischen Kasse und am Kassen-Block. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin 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 WooCommerce und keine Basisauthentifizierung für Webhooks.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: der Zahlungslink wurde erstellt, und Adyen hat die Zahlung noch nicht bestätigt. Die Bestellnotiz zeigt den Zahlungslink, den Betrag und die Umgebung.

Processing, Completed or On Hold: die Zahlung wurde autorisiert. Der Status richtet sich nach Order status after payment. Die Bestellnotiz zeigt den Betrag, die PSP-Referenz und die Zahlungsmethode. Die Transaktions-ID ist die Adyen-PSP-Referenz.

On hold after payment: Adyen hat einen anderen Betrag oder eine andere Währung bestätigt als den Bestellbetrag. Die Bestellnotiz zeigt beide Werte, und die Bestellung wird nicht als bezahlt markiert. Eine bezahlte Bestellung wird ebenfalls auf Wartend gesetzt, wenn eine Erfassung fehlschlägt, weil das Geld nicht eingezogen wurde. Prüfen Sie die Zahlung in der Customer Area.

Failed: die Zahlung wurde abgelehnt. Bezahlte, wartende und stornierte Bestellungen werden durch eine abgelehnte Zahlung nicht verändert.

Cancelled: die Zahlung dieser Bestellung wurde in Adyen storniert.

Trifft eine zweite erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein, etwa über einen alten Zahlungslink, wird die Bestellung nicht erneut verändert. Eine Notiz bittet Sie, in der Customer Area nach einer doppelten Belastung zu sehen und diese bei Bedarf dort zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Adyen. Vollständige und Teilerstattungen werden unterstützt. Die Erstattung wird an die Umgebung und das Händlerkonto gesendet, mit denen die Zahlung erfolgte; deshalb muss der API-Schlüssel dieser Umgebung eingetragen sein. Adyen verarbeitet Erstattungen asynchron: Die Anfrage wird an der Bestellung vermerkt, und das endgültige Ergebnis wird über den Webhook REFUND oder REFUND_FAILED als Bestellnotiz ergänzt. Akzeptiert Adyen die Anfrage nicht, zeigt WooCommerce den Fehler an, und es wird keine Erstattung verbucht. Bei manueller Erfassung in Adyen können nur erfasste Zahlungen erstattet werden.

Erstattungen, die in der Adyen Customer Area vorgenommen werden, kommen per Webhook an und werden den Bestellnotizen hinzugefügt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Adyen. 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, und 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 gilt für eine 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 Adyen Kunden an der Kasse nicht angezeigt. Versucht trotzdem jemand, eine Zahlung zu starten, sieht der Kunde This payment method is not available. Please choose another one. 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. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen bleiben unberührt: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, doch Updates und Support erfordern eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

Adyen erscheint nicht an der Kasse: prüfen Sie, ob 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 sowie im Live-Modus Live URL prefix. Die Einstellungsseite listet auf, was fehlt.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt bei Pending payment: der Webhook funktioniert nicht. Prüfen Sie in der Customer Area der verwendeten Umgebung (Test oder Live), ob der Standard-Webhook existiert, ob seine URL genau der in den Einstellungen angezeigten entspricht und ob das Format JSON ist. Prüfen Sie außerdem, ob 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 Plugin mit HTTP 401, und Adyen wiederholt die Zustellung später; sobald der Schlüssel korrigiert ist, wird die Bestellung automatisch aktualisiert. Das Protokoll zeigt Webhook rejected: invalid HMAC signature oder dass der HMAC-Schlüssel nicht konfiguriert ist.

Der Webhook antwortet mit „busy, retry later“: die Bestellung wurde im selben Moment von einer anderen Zustellung verarbeitet. Adyen wiederholt den Webhook automatisch.

Fehler beim HMAC-Schlüssel beim Speichern: das Feld muss den hexadezimalen HMAC-Schlüssel aus der Customer Area enthalten. Der vorherige Wert bleibt erhalten.

Der Kunde sieht „Payment could not be initiated“: öffnen Sie die Bestellnotizen oder schalten Sie das Debug log ein und sehen Sie in WooCommerce > Status > Logs, Quelle wcp_adyen_gateway, nach. Prüfen Sie den API-Schlüssel, das Händlerkonto und im Live-Modus das Live-URL-Präfix.

Die Bestellung ist nach der Zahlung auf Wartend: lesen Sie die Bestellnotiz. Der von Adyen bestätigte Betrag oder die Währung stimmte nicht mit der Bestellung überein, oder eine Erfassung ist fehlgeschlagen. Auch Ihre Einstellung Order status after payment kann die Ursache sein.

Erstattung schlägt fehl: die Bestellung braucht eine Adyen-PSP-Referenz, die mit dem AUTHORISATION-Webhook eintrifft. Die Zugangsdaten der Umgebung, in der die Zahlung erfolgte, müssen eingetragen sein. Bei manueller Erfassung können nur erfasste Zahlungen erstattet werden.

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. Hat sich 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.

Deinstallation

Beim Deaktivieren des Plugins bleiben alle Daten erhalten. 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 und die Adyen-Daten an den Bestellungen (PSP-Referenzen, Zahlungslinks, verarbeitete Ereignisse) werden nur entfernt, wenn Delete data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Adyen ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Adyen verbunden noch von Adyen empfohlen.