Adyen API, dünya genelindeki işletmeler için ödeme işlemlerini güçlendirerek geliştiricilerin çevrimiçi, mobil ve yüz yüze kanallar aracılığıyla işlemleri yönetmesini sağlar. Mühendisler, yüksek yetkilendirme oranları ve sağlam dolandırıcılık önleme sağlayarak 150'den fazla para biriminde 250'den fazla ödeme yöntemini desteklemek için bu API'yi entegre ederler. Güvenli ödeme sistemleri oluştururken, testi basitleştiren araçlar vazgeçilmez hale gelir.
Bu makale, Adyen API'ye erişme ve kullanma konusunda teknik bir rehber sunmaktadır. Geliştiriciler genellikle temel kurulumlarla başlar ve ileri düzey özelliklere doğru ilerler; bu nedenle rehber de bu ilerlemeyi takip eder. Öncelikle temelleri anlayın, ardından pratik uygulamaya geçin.
Adyen API Nedir?
Adyen API , ödeme ağ geçitleri için birleşik bir arayüz görevi görerek uygulamaların işlemleri güvenli bir şekilde gerçekleştirmesini sağlar. Platform, aracıları atlayarak doğrudan kart ağlarına ve yerel ödeme yöntemlerine bağlanır. Bu doğrudan bağlantı verimliliği artırır ve maliyetleri düşürür.
Adyen, çevrimiçi ödemeler için Checkout, abonelikler için Recurring, fon transferleri için Payouts ve satış noktası terminalleri için Yüz Yüze Ödemeler (In-Person Payments) dahil olmak üzere çeşitli API kategorileri sunar. Ayrıca, Platform API'leri pazar yeri çözümlerini desteklerken, BinLookup ücret hesaplamalarına ve 3D Secure kontrollerine yardımcı olur.
Mühendisler bunlara RESTful uç noktaları aracılığıyla erişir ve istekler JSON formatında düzenlenir. Örneğin, Checkout API ödeme başlatmayı yönetirken, Webhook'lar sistemlere durum değişikliklerini bildirir. Adyen, URL'lere /v68 gibi son ekler ekleyerek sürümleme yoluyla geriye dönük uyumluluğu korur.
Ayrıca Adyen, Java, Node.js, Python ve .NET gibi dillerde istemci kütüphaneleri sağlayarak çağrıları basitleştirir. Geliştiriciler bunları paket yöneticileri aracılığıyla kurar; örneğin, Node.js kütüphanesi için npm kullanarak. Bu kurulum, düşük seviyeli HTTP etkileşimlerini soyutlayarak geliştirmeyi hızlandırır.
Ancak, Adyen API'nin çalışması için doğru yapılandırma gereklidir. Kimlik bilgileri olmadan istekler kimlik doğrulama hatalarıyla başarısız olur. Bu nedenle, hesap kurulumu temel oluşturur.
Ödeme İhtiyaçlarınız İçin Neden Adyen API'yi Seçmelisiniz?
İşletmeler, Adyen API'yi ölçeklenebilirliği ve küresel erişimi nedeniyle tercih ederler. Sistem, Uber ve eBay gibi şirketler için yılda milyarlarca işlemi işler. RevenueProtect özelliği, dolandırıcılığı tespit etmek için makine öğrenimini kullanır, meşru ödemeleri onaylarken ters ibrazları en aza indirir.
Ek olarak, Adyen başarısız yetkilendirmeleri otomatik olarak yeniden deneyen akıllı yönlendirme ile geliri optimize eder. Bu, başarı oranlarını %5'e kadar artırır. Pazar yerleri için MarketPay, satıcılar arasındaki fon paylaşımlarını düzenlemelere uygun olarak yönetir.
Stripe veya PayPal gibi alternatiflerle karşılaştırıldığında, Adyen birleşik ticarette üstündür; çevrimiçi ve çevrimdışı ödemeleri tek bir sözleşme altında birleştirir. Geliştiriciler, uç noktaları etkileşimli olarak test etmelerini sağlayan ayrıntılı dokümantasyonu ve API Explorer'ı takdir eder.
Yine de, entegrasyon teknik uzmanlık gerektirir. Basit kurulumlar saatler sürerken, özel akışlar günler alır. Apidog, hızlı mock'lar ve testler sağlayarak bu süreci geliştirir ve güvenilirliği sağlar.
Şimdi, başlamak için ortamınızı yapılandırın.
Adyen Test Hesabı Nasıl Kurulur?
Gerçek fonlar olmadan deneme yapmak için bir test hesabı oluşturursunuz. Adyen web sitesini ziyaret edin ve bir geliştirici hesabı için kaydolun. Şirket adı ve konum dahil olmak üzere işletme ayrıntılarını sağlayın. Adyen başvuruları inceler ve genellikle birkaç gün içinde onaylar.
Onaylandıktan sonra, ca-test.adyen.com adresindeki Müşteri Alanı'na giriş yapın. Burada, e-ticaret için -ECOM ile biten işyeri hesaplarını yönetirsiniz. Test ortamı, Adyen'in dokümantasyonundaki sahte kart numaralarını kullanarak işlemleri simüle eder.
Örneğin, Visa testleri için CVV 737 olan 4111 1111 1111 1111 kartını kullanın. Kontrol panelinde iDEAL veya Klarna gibi ödeme yöntemlerini etkinleştirin. Bu adım, entegrasyonunuzun bölgesel tercihleri desteklemesini sağlar.
Ayrıca, test ortamını canlı ortamdan ayırın. Test URL'leri test.adyen.com kullanırken, canlı URL'ler [rastgele]-[Şirket] gibi benzersiz bir ön ek içerir. Adyen, ücretlendirmelerden kaçınmak için test modunda başlamayı tavsiye eder.
Kurulumdan sonra, isteklerin kimliğini doğrulamak için kimlik bilgilerini alın.
API Kimlik Bilgileri ve İstemci Anahtarı Nasıl Alınır?
API anahtarlarını Müşteri Alanı'nda Geliştiriciler > API kimlik bilgileri altında oluşturursunuz. ws@Company.[ŞirketHesabınız] gibi satıcı düzeyinde bir kimlik bilgisi seçin. Mevcut değilse yeni bir anahtar oluşturun.
API anahtarı Aq42_...'ye benzer ve uç noktalara erişim sağlar. Adyen bunu tekrar göstermediği için güvenli bir şekilde kopyalayın. Ardından, istemci tarafı kimlik doğrulaması için aynı sayfada test_ veya live_ ön ekiyle bir İstemci Anahtarı oluşturun.
CORS sorunlarını önlemek için http://localhost:8080 gibi izin verilen kaynakları ekleyin. Değişiklikleri kaydedin. Bu anahtarlar, sunucu tarafı çağrılarını ve Drop-in gibi ön uç bileşenlerini etkinleştirir.
Anahtarları ortam değişkenlerinde veya yapılandırma dosyalarında saklayın, asla kod depolarında değil. Java uygulamaları için bunları özellik dosyaları aracılığıyla enjekte edin. Bu uygulama güvenliği artırır.
Kimlik bilgileri hazır olduğunda, kimlik doğrulamayı keşfedin.
Adyen API İçin Kimlik Doğrulama Yöntemleri Nelerdir?
Adyen, temel kimlik doğrulaması için API anahtarlarını kullanır. Sunucu tarafı istekleri için anahtarı X-API-Key başlığına ekleyin. Örneğin:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
İstemci tarafı, Adyen.Web gibi kütüphaneleri başlatmak için İstemci Anahtarını kullanır. Bu, endişeleri ayırır ve maruz kalmayı azaltır.
Webhook'lar HMAC doğrulaması gerektirir. Adyen bildirimleri, kütüphaneler kullanarak doğruladığınız bir HMAC anahtarı ile imzalar. Geçersiz imzalar kurcalanma olduğunu gösterir.
Ek olarak, bazı uç noktalar OAuth için Taşıyıcı (Bearer) jetonlarını desteklese de, çoğu entegrasyon için API anahtarları yeterlidir. İletimleri şifrelemek için her zaman HTTPS kullanın.
Yanlış yapılandırılmış kimlik doğrulama 401 hatalarına yol açar. Bu nedenle, kimlik bilgilerini erken test edin.
Şimdi, temel uç noktaları inceleyelim.
Adyen API'deki Temel Uç Noktaları Keşfetmek
Adyen API, uç noktaları fonksiyona göre düzenler. /paymentMethods uç noktası, konuma ve para birimine göre mevcut yöntemleri alır. merchantAccount ile bir POST gönderin:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
Yanıt, kartlar veya iDEAL gibi yöntemleri listeler.
/payments uç noktası işlemleri başlatır. Miktar, paymentMethod ve referansı dahil edin:
{
"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"
}
Başarılı yanıtlar Authorised gibi resultCode içerir.
Ayrıntılar için, 3DS sonuçları gibi ek verileri göndermek üzere /payments/details kullanın.
/recurring gibi Yinelenen API uç noktaları depolanmış kimlik bilgilerini yönetir. Payouts API fon transferlerini yönetir.
Apidog, koleksiyonları içe aktararak, parametre ayarlamalarına ve yanıt doğrulamasına izin vererek bunları keşfetmeyi basitleştirir.
Uygulamaya geçiş yaparken şu adımları izleyin.
Adım Adım Kılavuz: Adyen API'yi Uygulamanıza Entegre Etme
Geliştiriciler, Adyen API'yi sunucu tarafı ve istemci tarafı bileşenlerini kullanarak entegre eder. Java Spring Boot gibi bir arka uç framework'ü ile başlayın.
İlk olarak, Adyen kütüphanesini ekleyin. build.gradle'da:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
İstemciyi yapılandırın:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
Ön uçta, Adyen.Web'i dahil edin:
<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">
Ödeme yöntemlerini alın:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
Drop-in'i başlatın:
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');
Ödemeler için, bir arka uç uç noktası oluşturun:
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);
browserInfo ve origin ekleyerek 3D Secure'u yönetin. Eğer action.type redirect ise, kullanıcıyı yönlendirin.
Webhook'lar için, POST isteklerini almak üzere bir uç nokta kurun. HMAC'yi doğrulayın:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
Kontrol panelinde belirli yöntemleri etkinleştirin. iDEAL için:
paymentMethod'a düzenleyici seçimi ekleyin.
Klarna için, lineItems'ı dahil edin:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Adyen'in kart uzantısı veya manuel girişlerle test edin.
Bu entegrasyon temel akışları destekler. Tokenizasyon için genişletin: /payments ile ayrıntıları depolayın, storeDetails: true olarak ayarlayın.
Ön yetkilendirme, daha sonra /captures aracılığıyla yakalanır.
Apidog, yanıtları taklit ederek, uç durumları test ederek yardımcı olur.
Adyen API Testi İçin Apidog Nasıl Kullanılır?
Apidog, Adyen API testini kolaylaştırır. Ücretsiz sürümü indirin ve Adyen koleksiyonunu içe aktarın.
Örneğin, /adjustAuthorisation için bir cURL yapıştırın:
Apidog bunu ayrıştırır, alanları doldurur. Yanıtları görüntülemek için gönderin.
Akışları test edin: Yetkilendirin, sonra yakalayın. Durum kodları için iddialar kullanın.
Apidog, gecikmeleri veya hataları simüle eden uç noktaları taklit eder. Otomatik çalıştırmalar için CI/CD ile entegre edin.
Adyen için, istekleri zincirleyerek 3DS gibi güvenliği doğrulayın.
Ayrıca, belirtimlerden belgeler oluşturun, ekiplerle paylaşın.
Bu araç, manuel çabayı azaltır ve sorunları erken yakalar.
Adyen API Kullanımı İçin En İyi Uygulamalar
Kopyaları önlemek için idempotency anahtarları uygulayın: RequestOptions'ta UUID'yi ayarlayın.
İstemci tarafı güvenliği için oturum akışını kullanın, oturumları sunucu tarafında oluşturun.
Performansı webhook'larla izleyin, olayları günlüğe kaydedin.
Hassas veri depolamaktan kaçınarak PCI DSS'e uyun.
Ödemeleri toplu işleyerek ölçeklendirin.
Ayrıca, özellikler için kütüphaneleri düzenli olarak güncelleyin.
Sık Karşılaşılan Sorunlar ve Sorun Giderme
401 Yetkisiz: API anahtarını kontrol edin.
Geçersiz HMAC: Anahtarın eşleştiğini doğrulayın.
Reddedilen ödemeler: Test kartlarını doğru kullanın.
CORS hataları: Kaynakları ekleyin.
Müşteri Alanı'ndaki günlükleri inceleyin.
Gelişmiş Özellikler: 3D Secure, Webhook'lar ve Daha Fazlası
Dinamik 3DS'yi etkinleştirin: attemptAuthentication: always olarak ayarlayın.
Webhook'lar eşzamansız olarak bildirir—AUTHORISATION olaylarını ele alın.
Platformlar için, /transfers kullanın.
Ücretler için BinLookup'u entegre edin.
Apidog bunları senaryolarla test eder.
Sonuç
Artık Adyen API'ye etkili bir şekilde nasıl erişeceğinizi ve kullanacağınızı biliyorsunuz. Kurulumdan gelişmiş entegrasyonlara kadar bu rehber, geliştiricileri donatır. Test modunda deney yapın, ardından canlıya geçin. Apidog gibi araçlar bu süreci hızlandırır.