Adyen Provider Account einrichten

Diese Anleitung beschreibt, die Einrichtung eines Adyen Provider Accounts in copal. Die benötigten Werte sind im Adyen-Backend zu finden.

Übersicht: Benötigte Daten

ApiKey

Der ApiKey ermöglicht collana pay die Kommunikation mit der Adyen API. Er wird benötigt, um Zahlungen zu verarbeiten, Rückbuchungen zu verwalten und weitere API-Aktionen auszuführen.

1. Melden Sie sich in Ihrer Adyen Customer Area an.
2. Navigieren Sie zu Developers → API credentials.
3. Erstellen Sie neue Credentials. Der Benutzername wird automatisch generiert. Vergeben Sie eine eindeutige Beschreibung, z. B. „collana pay Sandbox" oder „collana pay Live".
4. Nach dem Speichern wird der ApiKey angezeigt. Kopieren Sie ihn und bewahren Sie ihn sicher auf.
5. Klicken Sie auf „Save changes".

Adyen-Dokumentation: API Key generieren

CustomerEndpointPrefix (nur relevant im Live-Tenant)

Jedes Company-Konto bei Adyen erhält einen eigenen Hostnamen für die Kommunikation mit der Adyen-API. Der Prefix ist eine Zeichenfolge, die aus einem hex-kodierten Zufallsteil und Ihrem Firmennamen besteht.

Den Prefix finden Sie in Ihrer Live Customer Area unter Developers → API URLs. Dort sehen Sie den eindeutigen Prefix für Ihre Region.

Adyen-Dokumentation: Live-Endpunkte

MerchantId

Die MerchantId (Account Code) identifiziert Ihren Merchant Account eindeutig. Wenn Sie verschiedene Merchant Accounts für unterschiedliche Länder- oder Währungskombinationen verwenden, werden unterschiedliche Merchant Ids benötigt.

1. Melden Sie sich in Ihrer Adyen Customer Area an.
2. Navigieren Sie zu Settings → Account Groups.
3. Den Account Code des gewünschten Merchant Accounts finden Sie in der Übersicht.

Adyen-Dokumentation: Account-Struktur

Webhook konfigurieren

Webhooks stellen sicher, dass collana pay Benachrichtigungen über Zahlungsereignisse von Adyen erhält (z. B. erfolgreiche Zahlung, Stornierung). Ohne diese Konfiguration können Bestellstatus nicht korrekt aktualisiert werden.

💡 Empfehlung: Richten Sie den Webhook auf Company-Ebene ein – so gilt er für alle Merchant Accounts und muss nur einmal konfiguriert werden.

Neuen Webhook anlegen

1. Navigieren Sie in der Adyen Customer Area zu Developers → Webhooks.
2. Klicken Sie auf „Create new webhook" und wählen Sie „Standard Webhook" als Webhook-Typ.

Allgemeine Einstellungen (General)

1. Description: Vergeben Sie eine aussagekräftige Beschreibung, z. B. „collana pay Webhook".
2. Server configuration – URL: Tragen Sie die collana pay Notification-URL ein:
   • Sandbox: https://sandbox.collanapay.com/v2/notifications/adyen/
   • Produktion: https://live.collanapay.com/v2/notifications/adyen/
3. Server configuration – Method: Wählen Sie JSON.
4. Events: Belassen Sie die Einstellung auf „Default events enabled". Zusätzliche Events können bei Bedarf aktiviert werden (siehe Abschnitt Zusätzliche Events aktivieren)

Sicherheitseinstellungen (Security)

1. Basic Authentication – Username (NotificationsAuthenticationUserName): Legen Sie einen Benutzernamen fest.
2. Basic Authentication – Password (NotificationsAuthenticationPassword): Legen Sie ein Passwort fest.
3. HMAC Key (NotificationsHmacKey): Klicken Sie auf „Generate", um einen neuen HMAC-Schlüssel zu erstellen.
   
   Der HMAC-Schlüssel (Hash-based Message Authentication Code) stellt sicher, dass Webhook-Nachrichten von Adyen stammen und nicht manipuliert wurden.

Klicken Sie abschließend auf „Save changes".

Adyen-Dokumentation: Webhook einrichten

Zusätzliche Events aktivieren

In der Webhook-Konfiguration sollte das Event OFFER_CLOSED aktiviert werden. Dadurch wird sichergestellt, dass auch im Fall eines abgebrochenen Zahlungsvorgangs (z. B. wenn der Shopper den Zahlungsprozess nicht abschließt) der Status der Bestellung korrekt auf "Canceled" gesetzt wird. Anderenfalls bleibt der Status auf "Pending". Zudem ermöglicht dies, dass der Shopper ordnungsgemäß zurück an den Webshop geleitet wird.

Das Event EXPIRE wird ausgelöst, wenn eine erfolgreiche Reservierung abläuft und danach nicht mehr gecaptured werden kann.