Die Adyen API unterstützt die Zahlungsabwicklung für Unternehmen weltweit und ermöglicht Entwicklern, Transaktionen über Online-, Mobil- und persönliche Kanäle abzuwickeln. Ingenieure integrieren diese API, um über 250 Zahlungsmethoden in mehr als 150 Währungen zu unterstützen, was hohe Autorisierungsraten und eine robuste Betrugsprävention gewährleistet. Beim Aufbau sicherer Zahlungssysteme werden Tools, die das Testen vereinfachen, unerlässlich.
Dieser Artikel bietet eine technische Anleitung zum Zugriff und zur Nutzung der Adyen API. Entwickler beginnen oft mit grundlegenden Setups und gehen dann zu erweiterten Funktionen über, daher folgt der Leitfaden dieser Progression. Zuerst die Grundlagen verstehen, dann zur praktischen Implementierung übergehen.
Was ist die Adyen API?
Die Adyen API dient als einheitliche Schnittstelle für Zahlungs-Gateways und ermöglicht Anwendungen, Transaktionen sicher zu verarbeiten. Die Plattform verbindet sich direkt mit Kartennetzwerken und lokalen Zahlungsmethoden, wodurch Vermittler umgangen werden. Diese direkte Verbindung steigert die Effizienz und reduziert Kosten.
Adyen bietet verschiedene API-Kategorien, darunter Checkout für Online-Zahlungen, Recurring für Abonnements, Payouts für Geldtransfers und In-Person Payments für Point-of-Sale-Terminals. Darüber hinaus unterstützen Plattform-APIs Marktplatzlösungen, während BinLookup bei Gebührenberechnungen und 3D Secure-Prüfungen hilft.
Ingenieure greifen über RESTful-Endpunkte darauf zu, wobei Anfragen im JSON-Format vorliegen. Zum Beispiel verwaltet die Checkout API die Initiierung von Zahlungen, während Webhooks Systeme über Statusänderungen informieren. Adyen gewährleistet Abwärtskompatibilität durch Versionierung, indem Suffixe wie /v68 an URLs angehängt werden.
Darüber hinaus stellt Adyen Client-Bibliotheken in Sprachen wie Java, Node.js, Python und .NET bereit, die Aufrufe vereinfachen. Entwickler installieren diese über Paketmanager – zum Beispiel mit npm für die Node.js-Bibliothek. Diese Einrichtung beschleunigt die Entwicklung, indem sie Low-Level-HTTP-Interaktionen abstrahiert.
Die Adyen API erfordert jedoch eine ordnungsgemäße Konfiguration, um zu funktionieren. Ohne Anmeldeinformationen schlagen Anfragen mit Authentifizierungsfehlern fehl. Daher bildet die Kontoeinrichtung die Grundlage.
Warum die Adyen API für Ihre Zahlungsanforderungen wählen?
Unternehmen wählen die Adyen API aufgrund ihrer Skalierbarkeit und globalen Reichweite. Das System verarbeitet jährlich Milliarden von Transaktionen für Unternehmen wie Uber und eBay. Die RevenueProtect-Funktion nutzt maschinelles Lernen zur Betrugserkennung, minimiert Rückbuchungen und genehmigt gleichzeitig legitime Zahlungen.
Zusätzlich optimiert Adyen den Umsatz durch intelligentes Routing, indem fehlgeschlagene Autorisierungen automatisch wiederholt werden. Dies erhöht die Erfolgsquoten um bis zu 5 %. Für Marktplätze wickelt MarketPay die Aufteilung der Gelder unter den Verkäufern ab und erfüllt dabei die Vorschriften.
Im Vergleich zu Alternativen wie Stripe oder PayPal zeichnet sich Adyen im Unified Commerce aus – der Kombination von Online- und Offline-Zahlungen unter einem einzigen Vertrag. Entwickler schätzen die detaillierte Dokumentation und den API Explorer, mit denen sie Endpunkte interaktiv testen können.
Dennoch erfordert die Integration technisches Fachwissen. Einfache Setups dauern Stunden, aber benutzerdefinierte Abläufe erfordern Tage. Apidog verbessert diesen Prozess, indem es schnelle Mocks und Tests ermöglicht und so die Zuverlässigkeit gewährleistet.
Konfigurieren Sie als Nächstes Ihre Umgebung, um zu beginnen.
Wie richtet man ein Adyen-Testkonto ein?
Sie erstellen ein Testkonto, um ohne echte Gelder zu experimentieren. Besuchen Sie die Adyen-Website und registrieren Sie sich für ein Entwicklerkonto. Geben Sie Geschäftsdaten an, einschließlich Firmenname und Standort. Adyen prüft Anträge und genehmigt diese in der Regel innerhalb weniger Tage.
Nach der Genehmigung melden Sie sich im Customer Area unter ca-test.adyen.com an. Hier verwalten Sie Händlerkonten, die auf -ECOM für E-Commerce enden. Die Testumgebung simuliert Transaktionen unter Verwendung gefälschter Kartennummern aus der Adyen-Dokumentation.
Verwenden Sie zum Beispiel die Karte 4111 1111 1111 1111 mit CVV 737 für Visa-Tests. Aktivieren Sie Zahlungsmethoden wie iDEAL oder Klarna im Dashboard. Dieser Schritt stellt sicher, dass Ihre Integration regionale Präferenzen unterstützt.
Unterscheiden Sie außerdem zwischen Test- und Live-Umgebungen. Test-URLs verwenden test.adyen.com, während Live-URLs ein eindeutiges Präfix wie [random]-[Company] enthalten. Adyen empfiehlt, im Testmodus zu beginnen, um Gebühren zu vermeiden.
Nach der Einrichtung erhalten Sie Anmeldeinformationen zur Authentifizierung von Anfragen.
Wie erhält man API-Zugangsdaten und den Client-Schlüssel?
Sie generieren API-Schlüssel im Customer Area unter Entwickler > API-Zugangsdaten. Wählen Sie eine Anmeldeinformation auf Händlerebene, z. B. ws@Company.[IhrUnternehmenskonto]. Erstellen Sie einen neuen Schlüssel, falls keiner vorhanden ist.
Der API-Schlüssel ähnelt Aq42_... und gewährt Zugriff auf Endpunkte. Kopieren Sie ihn sicher, da Adyen ihn nicht erneut anzeigt. Als Nächstes generieren Sie auf derselben Seite einen Client-Schlüssel für die clientseitige Authentifizierung, der mit test_ oder live_ präfixiert ist.
Fügen Sie zulässige Ursprünge hinzu, wie http://localhost:8080, um CORS-Probleme zu vermeiden. Speichern Sie die Änderungen. Diese Schlüssel ermöglichen serverseitige Aufrufe und Frontend-Komponenten wie Drop-in.
Speichern Sie Schlüssel in Umgebungsvariablen oder Konfigurationsdateien, niemals in Code-Repositories. Für Java-Anwendungen injizieren Sie sie über Properties-Dateien. Diese Praxis erhöht die Sicherheit.
Nachdem die Anmeldeinformationen bereit sind, untersuchen Sie die Authentifizierung.
Was sind die Authentifizierungsmethoden für die Adyen API?
Adyen verwendet API-Schlüssel für die Basisauthentifizierung. Fügen Sie den Schlüssel im X-API-Key-Header für serverseitige Anfragen ein. Zum Beispiel:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
Clientseitig wird der Client-Schlüssel verwendet, um Bibliotheken wie Adyen.Web zu initialisieren. Dies trennt Verantwortlichkeiten und reduziert die Offenlegung.
Webhooks erfordern eine HMAC-Validierung. Adyen signiert Benachrichtigungen mit einem HMAC-Schlüssel, den Sie mithilfe von Bibliotheken überprüfen. Ungültige Signaturen weisen auf Manipulationen hin.
Zusätzlich unterstützen einige Endpunkte Bearer-Tokens für OAuth, aber API-Schlüssel reichen für die meisten Integrationen aus. Verwenden Sie immer HTTPS, um Übertragungen zu verschlüsseln.
Fehlkonfigurierte Authentifizierung führt zu 401-Fehlern. Testen Sie daher Anmeldeinformationen frühzeitig.
Untersuchen Sie nun die Kern-Endpunkte.
Erkundung wichtiger Endpunkte in der Adyen API
Die Adyen API organisiert Endpunkte nach Funktion. Der Endpunkt /paymentMethods ruft verfügbare Methoden basierend auf Standort und Währung ab. Senden Sie eine POST-Anfrage mit merchantAccount:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
Die Antwort listet Methoden wie Karten oder iDEAL auf.
Der Endpunkt /payments initiiert Transaktionen. Fügen Sie Betrag, Zahlungsmethode und Referenz ein:
{
"amount": {
"currency": "EUR",
"value": 1000
},
"reference": "YOUR_REFERENCE",
"paymentMethod": {
"type": "scheme",
"number": "4111111111111111",
"expiryMonth": "03",
"expiryYear": "2030",
"cvc": "737"
},
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"returnUrl": "https://your-site.com/return"
}
Erfolgreiche Antworten enthalten resultCode wie Authorised.
Für Details verwenden Sie /payments/details, um zusätzliche Daten, wie z.B. 3DS-Ergebnisse, zu übermitteln.
Recurring API-Endpunkte wie /recurring verwalten gespeicherte Anmeldeinformationen. Die Payouts API verwaltet Geldtransfers.
Apidog vereinfacht die Erkundung dieser, indem es das Importieren von Sammlungen ermöglicht, was Parameteranpassungen und die Validierung von Antworten erlaubt.
Für die Implementierung folgen Sie diesen Schritten.
Schritt-für-Schritt-Anleitung: Integration der Adyen API in Ihre Anwendung
Entwickler integrieren die Adyen API mithilfe von serverseitigen und clientseitigen Komponenten. Beginnen Sie mit einem Backend-Framework wie Java Spring Boot.
Zuerst die Adyen-Bibliothek hinzufügen. In build.gradle:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
Den Client konfigurieren:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
Im Frontend Adyen.Web einbinden:
<script src="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/5.0.0/adyen.js"></script>
<link rel="stylesheet" href="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/5.0.0/adyen.css">
Zahlungsmethoden abrufen:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
Drop-in initialisieren:
const configuration = {
paymentMethodsResponse: await getPaymentMethods(),
clientKey: "YOUR_CLIENT_KEY",
locale: "en_US",
environment: "test",
onSubmit: (state, dropin) => {
// Handle submission
}
};
const checkout = await AdyenCheckout(configuration);
checkout.create('dropin').mount('#dropin-container');
Für Zahlungen einen Backend-Endpunkt erstellen:
PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.merchantAccount("YOUR_MERCHANT_ACCOUNT");
paymentRequest.amount(new Amount().currency("EUR").value(1000L));
// Set other fields
PaymentResponse response = paymentsApi.payments(paymentRequest);
3D Secure behandeln, indem browserInfo und origin hinzugefügt werden. Wenn action.type ein Redirect ist, leiten Sie den Benutzer weiter.
Für Webhooks richten Sie einen Endpunkt ein, um POST-Anfragen zu empfangen. HMAC validieren:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
Spezifische Methoden im Dashboard aktivieren. Für iDEAL:
Auswahl des Emittenten in paymentMethod hinzufügen.
Für Klarna lineItems hinzufügen:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Mit Adyens Kartenerweiterung oder manuellen Eingaben testen.
Diese Integration unterstützt grundlegende Abläufe. Für Tokenisierung erweitern: Details mit /payments speichern, storeDetails: true setzen.
Vorautorisierung erfasst später über /captures.
Apidog unterstützt durch das Simulieren von Antworten und das Testen von Grenzsituationen.
Wie man Apidog zum Testen der Adyen API verwendet?
Apidog optimiert das Testen der Adyen API. Laden Sie die kostenlose Version herunter und importieren Sie die Adyen-Sammlung.
Fügen Sie zum Beispiel einen cURL-Befehl für /adjustAuthorisation ein:
Apidog parst ihn und füllt Felder aus. Senden, um Antworten anzuzeigen.
Testabläufe: Autorisieren, dann erfassen. Assertionen für Statuscodes verwenden.
Apidog simuliert Endpunkte und verzögert oder emuliert Fehler. Integrieren Sie es mit CI/CD für automatisierte Ausführungen.
Für Adyen validieren Sie die Sicherheit wie 3DS durch das Verketten von Anfragen.
Zusätzlich Dokumente aus Spezifikationen generieren und mit Teams teilen.
Dieses Tool reduziert den manuellen Aufwand und fängt Probleme frühzeitig ab.
Best Practices für die Verwendung der Adyen API
Implementieren Sie Idempotenzschlüssel, um Duplikate zu vermeiden: Setzen Sie UUID in RequestOptions.
Verwenden Sie den Sessions-Flow für clientseitige Sicherheit, wobei Sessions serverseitig generiert werden.
Überwachen Sie die Leistung mit Webhooks, protokollieren Sie Ereignisse.
Halten Sie die PCI DSS-Vorschriften ein, indem Sie die Speicherung sensibler Daten vermeiden.
Skalieren Sie durch das Stapeln von Auszahlungen.
Aktualisieren Sie außerdem Bibliotheken regelmäßig für neue Funktionen.
Häufige Probleme und Fehlerbehebung
401 Unauthorized: API-Schlüssel überprüfen.
Ungültiger HMAC: Schlüsselabgleich überprüfen.
Abgelehnte Zahlungen: Testkarten korrekt verwenden.
CORS-Fehler: Ursprünge hinzufügen.
Protokolle im Customer Area konsultieren.
Erweiterte Funktionen: 3D Secure, Webhooks und mehr
Dynamisches 3DS aktivieren: Setzen Sie attemptAuthentication: always.
Webhooks benachrichtigen asynchron – behandeln Sie AUTHORISATION-Ereignisse.
Für Plattformen verwenden Sie /transfers.
BinLookup für Gebühren integrieren.
Apidog testet diese mit Szenarien.
Fazit
Sie wissen nun, wie Sie die Adyen API effektiv nutzen können. Von der Einrichtung bis zu erweiterten Integrationen rüstet dieser Leitfaden Entwickler aus. Experimentieren Sie im Testmodus und gehen Sie dann live. Tools wie Apidog beschleunigen den Prozess.