L'API Adyen alimente le traitement des paiements pour les entreprises du monde entier, permettant aux développeurs de gérer les transactions via les canaux en ligne, mobiles et en personne. Les ingénieurs intègrent cette API pour prendre en charge plus de 250 méthodes de paiement dans plus de 150 devises, garantissant des taux d'autorisation élevés et une prévention robuste de la fraude. Lorsque vous construisez des systèmes de paiement sécurisés, les outils qui simplifient les tests deviennent essentiels.
Cet article propose une présentation technique sur l'accès et l'utilisation de l'API Adyen. Les développeurs commencent souvent par des configurations de base et progressent vers des fonctionnalités avancées, de sorte que le guide suit cette progression. D'abord, comprenez les fondamentaux, puis passez à la mise en œuvre pratique.
Qu'est-ce que l'API Adyen ?
L'API Adyen sert d'interface unifiée pour les passerelles de paiement, permettant aux applications de traiter les transactions en toute sécurité. La plateforme se connecte directement aux réseaux de cartes et aux méthodes de paiement locales, en contournant les intermédiaires. Cette connexion directe améliore l'efficacité et réduit les coûts.
Adyen propose plusieurs catégories d'API, y compris Checkout pour les paiements en ligne, Recurring pour les abonnements, Payouts pour les transferts de fonds et In-Person Payments pour les terminaux de point de vente. De plus, les API Platforms prennent en charge les solutions de marketplace, tandis que BinLookup aide au calcul des frais et aux vérifications 3D Secure.
Les ingénieurs y accèdent via des points de terminaison RESTful, avec des requêtes formatées en JSON. Par exemple, l'API Checkout gère les initiations de paiement, tandis que les Webhooks notifient les systèmes des changements de statut. Adyen maintient la compatibilité ascendante grâce au versioning, en ajoutant des suffixes comme /v68 aux URL.
De plus, Adyen fournit des bibliothèques clientes dans des langages tels que Java, Node.js, Python et .NET, simplifiant les appels. Les développeurs les installent via des gestionnaires de paquets — par exemple, en utilisant npm pour la bibliothèque Node.js. Cette configuration accélère le développement en abstraiyant les interactions HTTP de bas niveau.
Cependant, l'API Adyen nécessite une configuration appropriée pour fonctionner. Sans identifiants, les requêtes échouent avec des erreurs d'authentification. Par conséquent, la configuration du compte constitue la base.
Pourquoi choisir l'API Adyen pour vos besoins de paiement ?
Les entreprises choisissent l'API Adyen pour son évolutivité et sa portée mondiale. Le système traite des milliards de transactions chaque année pour des entreprises comme Uber et eBay. Sa fonctionnalité RevenueProtect utilise l'apprentissage automatique pour détecter la fraude, minimisant les rétrofacturations tout en approuvant les paiements légitimes.
De plus, Adyen optimise les revenus grâce à un routage intelligent, en réessayant automatiquement les autorisations échouées. Cela augmente les taux de réussite jusqu'à 5 %. Pour les marketplaces, MarketPay gère la répartition des fonds entre les vendeurs, en respectant les réglementations.
Comparé à des alternatives comme Stripe ou PayPal, Adyen excelle dans le commerce unifié — combinant paiements en ligne et hors ligne sous un seul contrat. Les développeurs apprécient la documentation détaillée et l'API Explorer, qui leur permet de tester les points de terminaison de manière interactive.
Néanmoins, l'intégration exige une expertise technique. Les configurations simples prennent des heures, mais les flux personnalisés nécessitent des jours. Apidog améliore ce processus en permettant des simulations et des tests rapides, garantissant la fiabilité.
Ensuite, configurez votre environnement pour commencer.
Comment configurer un compte de test Adyen ?
Vous créez un compte de test pour expérimenter sans fonds réels. Visitez le site web d'Adyen et inscrivez-vous pour un compte développeur. Fournissez les détails de l'entreprise, y compris le nom de l'entreprise et l'emplacement. Adyen examine les applications, les approuvant généralement en quelques jours.
Une fois approuvé, connectez-vous à la Customer Area sur ca-test.adyen.com. Ici, vous gérez les comptes marchands se terminant par -ECOM pour le commerce électronique. L'environnement de test simule les transactions, en utilisant des numéros de carte fictifs de la documentation d'Adyen.
Par exemple, utilisez la carte 4111 1111 1111 1111 avec le CVV 737 pour les tests Visa. Activez les méthodes de paiement comme iDEAL ou Klarna dans le tableau de bord. Cette étape garantit que votre intégration prend en charge les préférences régionales.
De plus, distinguez les environnements de test des environnements de production. Les URL de test utilisent test.adyen.com, tandis que celles de production incluent un préfixe unique comme [aléatoire]-[Entreprise]. Adyen conseille de commencer en mode test pour éviter les frais.
Après la configuration, obtenez les identifiants pour authentifier les requêtes.
Comment obtenir les identifiants API et la clé client ?
Vous générez des clés API dans la Customer Area sous Développeurs > Identifiants API. Sélectionnez un identifiant de niveau marchand, tel que ws@Company.[VotreCompteEntreprise]. Créez une nouvelle clé si aucune n'existe.
La clé API ressemble à Aq42_... et accorde l'accès aux points de terminaison. Copiez-la en toute sécurité, car Adyen ne l'affichera plus. Ensuite, générez une clé client sur la même page pour l'authentification côté client, précédée de test_ ou live_.
Ajoutez les origines autorisées, comme http://localhost:8080, pour éviter les problèmes CORS. Enregistrez les modifications. Ces clés permettent les appels côté serveur et les composants frontend comme Drop-in.
Stockez les clés dans des variables d'environnement ou des fichiers de configuration, jamais dans des dépôts de code. Pour les applications Java, injectez-les via des fichiers de propriétés. Cette pratique améliore la sécurité.
Avec les identifiants prêts, explorez l'authentification.
Quelles sont les méthodes d'authentification pour l'API Adyen ?
Adyen utilise des clés API pour l'authentification de base. Incluez la clé dans l'en-tête X-API-Key pour les requêtes côté serveur. Par exemple:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
Côté client, la clé client est utilisée pour initialiser des bibliothèques comme Adyen.Web. Cela sépare les préoccupations, réduisant l'exposition.
Les webhooks nécessitent une validation HMAC. Adyen signe les notifications avec une clé HMAC, que vous vérifiez à l'aide de bibliothèques. Des signatures invalides indiquent une altération.
De plus, certains points de terminaison prennent en charge les jetons Bearer pour OAuth, mais les clés API suffisent pour la plupart des intégrations. Utilisez toujours HTTPS pour chiffrer les transmissions.
Une authentification mal configurée entraîne des erreurs 401. Par conséquent, testez les identifiants tôt.
Maintenant, examinons les points de terminaison principaux.
Exploration des points de terminaison clés dans l'API Adyen
L'API Adyen organise les points de terminaison par fonction. Le point de terminaison /paymentMethods récupère les méthodes disponibles en fonction de l'emplacement et de la devise. Envoyez un POST avec merchantAccount:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
La réponse liste les méthodes comme les cartes ou iDEAL.
Le point de terminaison /payments initie les transactions. Incluez le montant, la méthode de paiement et la référence:
{
"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"
}
Les réponses réussies incluent un resultCode comme Authorised.
Pour plus de détails, utilisez /payments/details pour soumettre des données supplémentaires, telles que les résultats 3DS.
Les points de terminaison de l'API Recurring, comme /recurring, gèrent les identifiants stockés. L'API Payouts gère les transferts de fonds.
Apidog simplifie leur exploration en important des collections, permettant des ajustements de paramètres et la validation des réponses.
Pour passer à l'implémentation, suivez ces étapes.
Guide étape par étape : Intégrer l'API Adyen dans votre application
Les développeurs intègrent l'API Adyen en utilisant des composants côté serveur et côté client. Commencez avec un framework backend comme Java Spring Boot.
D'abord, ajoutez la bibliothèque Adyen. Dans build.gradle:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
Configurez le client:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
Sur le frontend, incluez Adyen.Web:
<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">
Récupérez les méthodes de paiement:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
Initialisez Drop-in:
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');
Pour les paiements, créez un point de terminaison backend:
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);
Gérez 3D Secure en ajoutant browserInfo et origin. Si action.type est redirect, redirigez l'utilisateur.
Pour les webhooks, configurez un point de terminaison pour recevoir les POSTs. Validez HMAC:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
Activez des méthodes spécifiques dans le tableau de bord. Pour iDEAL:
Ajoutez la sélection de l'émetteur dans paymentMethod.
Pour Klarna, incluez lineItems:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Testez avec l'extension de carte d'Adyen ou des entrées manuelles.
Cette intégration prend en charge les flux de base. Étendez-la pour la tokenisation : Stockez les détails avec /payments, en définissant storeDetails: true.
La préautorisation est capturée plus tard via /captures.
Apidog aide en simulant les réponses, testant les cas limites.
Comment utiliser Apidog pour tester l'API Adyen ?
Apidog simplifie les tests de l'API Adyen. Téléchargez la version gratuite et importez la collection Adyen.
Par exemple, collez une commande cURL pour /adjustAuthorisation:
Apidog l'analyse, remplissant les champs. Envoyez pour voir les réponses.
Testez les flux : Autoriser, puis capturer. Utilisez des assertions pour les codes de statut.
Apidog simule les points de terminaison, simulant des retards ou des erreurs. Intégrez avec CI/CD pour des exécutions automatisées.
Pour Adyen, validez la sécurité comme 3DS en chaînant les requêtes.
De plus, générez de la documentation à partir des spécifications, en la partageant avec les équipes.
Cet outil réduit l'effort manuel, détectant les problèmes tôt.
Meilleures pratiques pour l'utilisation de l'API Adyen
Implémentez des clés d'idempotence pour éviter les doublons : Définissez l'UUID dans RequestOptions.
Utilisez le flux de sessions pour la sécurité côté client, en générant des sessions côté serveur.
Surveillez les performances avec les webhooks, en enregistrant les événements.
Respectez la norme PCI DSS en évitant le stockage de données sensibles.
Évoluez en regroupant les paiements.
De plus, mettez à jour régulièrement les bibliothèques pour les fonctionnalités.
Problèmes courants et dépannage
401 Non autorisé : Vérifiez la clé API.
HMAC invalide : Vérifiez que la clé correspond.
Paiements refusés : Utilisez correctement les cartes de test.
Erreurs CORS : Ajoutez les origines.
Consultez les journaux dans la Customer Area.
Fonctionnalités avancées : 3D Secure, Webhooks, et plus encore
Activez 3DS dynamique : Définissez attemptAuthentication: always.
Les webhooks notifient de manière asynchrone — gérez les événements AUTHORISATION.
Pour les plateformes, utilisez /transfers.
Intégrez BinLookup pour les frais.
Apidog les teste avec des scénarios.
Conclusion
Vous savez maintenant comment accéder et utiliser l'API Adyen efficacement. De la configuration aux intégrations avancées, ce guide équipe les développeurs. Expérimentez en mode test, puis passez en production. Des outils comme Apidog accélèrent le processus.