تقوم واجهة برمجة تطبيقات Adyen (API) بتشغيل معالجة الدفع للشركات في جميع أنحاء العالم، مما يمكّن المطورين من التعامل مع المعاملات عبر القنوات عبر الإنترنت والهاتف المحمول والشخصية. يدمج المهندسون واجهة برمجة التطبيقات هذه لدعم أكثر من 250 طريقة دفع بأكثر من 150 عملة، مما يضمن معدلات تفويض عالية ومنعًا قويًا للاحتيال. أثناء بناء أنظمة دفع آمنة، تصبح الأدوات التي تبسط الاختبار ضرورية.
تقدم هذه المقالة شرحًا تقنيًا حول الوصول إلى واجهة برمجة تطبيقات Adyen واستخدامها. غالبًا ما يبدأ المطورون بالإعدادات الأساسية وينتقلون إلى الميزات المتقدمة، لذا يتبع الدليل هذا التسلسل. أولاً، فهم الأساسيات، ثم الانتقال إلى التنفيذ العملي.
ما هي واجهة برمجة تطبيقات Adyen؟
تعمل واجهة برمجة تطبيقات Adyen كواجهة موحدة لبوابات الدفع، مما يسمح للتطبيقات بمعالجة المعاملات بأمان. تتصل المنصة مباشرة بشبكات البطاقات وطرق الدفع المحلية، متجاوزة الوسطاء. يعزز هذا الاتصال المباشر الكفاءة ويقلل التكاليف.
تقدم Adyen عدة فئات من واجهات برمجة التطبيقات، بما في ذلك Checkout للمدفوعات عبر الإنترنت، وRecurring للاشتراكات، وPayouts لتحويلات الأموال، وIn-Person Payments لمحطات نقاط البيع. بالإضافة إلى ذلك، تدعم واجهات برمجة تطبيقات Platforms حلول الأسواق، بينما تساعد BinLookup في حساب الرسوم وفحوصات 3D Secure.
يصل المهندسون إلى هذه الواجهات عبر نقاط نهاية RESTful، مع طلبات منسقة بصيغة JSON. على سبيل المثال، تتعامل واجهة برمجة تطبيقات Checkout مع بدء المدفوعات، بينما تقوم Webhooks بإخطار الأنظمة بتغييرات الحالة. تحافظ Adyen على التوافق مع الإصدارات السابقة من خلال ترقيم الإصدارات، بإضافة لاحقات مثل /v68 إلى عناوين URL.
علاوة على ذلك، توفر Adyen مكتبات عميل بلغات مثل Java وNode.js وPython و.NET، مما يبسط الاستدعاءات. يقوم المطورون بتثبيتها عبر مديري الحزم—على سبيل المثال، باستخدام npm لمكتبة Node.js. يسرع هذا الإعداد من عملية التطوير عن طريق تجريد تفاعلات HTTP منخفضة المستوى.
ومع ذلك، تتطلب واجهة برمجة تطبيقات Adyen إعدادًا صحيحًا لتعمل. بدون بيانات الاعتماد، تفشل الطلبات بأخطاء المصادقة. لذلك، يشكل إعداد الحساب الأساس.
لماذا تختار واجهة برمجة تطبيقات Adyen لاحتياجات الدفع الخاصة بك؟
تختار الشركات واجهة برمجة تطبيقات Adyen لقابليتها للتوسع ونطاقها العالمي. يعالج النظام مليارات المعاملات سنويًا لشركات مثل Uber وeBay. تستخدم ميزة RevenueProtect الخاصة بها التعلم الآلي للكشف عن الاحتيال، مما يقلل من عمليات رد المبالغ المدفوعة مع الموافقة على المدفوعات المشروعة.
بالإضافة إلى ذلك، تعمل Adyen على تحسين الإيرادات من خلال التوجيه الذكي، وإعادة محاولة التفويضات الفاشلة تلقائيًا. وهذا يزيد من معدلات النجاح بنسبة تصل إلى 5%. بالنسبة للأسواق، يتعامل MarketPay مع تقسيم الأموال بين البائعين، بما يتوافق مع اللوائح.
بالمقارنة مع البدائل مثل Stripe أو PayPal، تتفوق Adyen في التجارة الموحدة—حيث تجمع بين المدفوعات عبر الإنترنت وغير المتصلة بالإنترنت بموجب عقد واحد. يقدر المطورون الوثائق التفصيلية ومستكشف واجهة برمجة التطبيقات (API Explorer)، مما يسمح لهم باختبار نقاط النهاية بشكل تفاعلي.
ومع ذلك، يتطلب التكامل خبرة فنية. تستغرق الإعدادات البسيطة ساعات، لكن التدفقات المخصصة تتطلب أيامًا. يعزز Apidog هذه العملية من خلال تمكين المحاكاة والاختبارات السريعة، مما يضمن الموثوقية.
بعد ذلك، قم بتكوين بيئتك للبدء.
كيف تقوم بإعداد حساب اختبار Adyen؟
تقوم بإنشاء حساب اختبار للتجربة بدون أموال حقيقية. قم بزيارة موقع Adyen للتسجيل في حساب مطور. قم بتقديم تفاصيل العمل، بما في ذلك اسم الشركة والموقع. تراجع Adyen الطلبات، وعادة ما توافق عليها في غضون أيام.
بمجرد الموافقة، سجل الدخول إلى منطقة العملاء على ca-test.adyen.com. هنا، تدير حسابات التجار التي تنتهي بـ -ECOM للتجارة الإلكترونية. تحاكي بيئة الاختبار المعاملات، باستخدام أرقام بطاقات وهمية من وثائق Adyen.
على سبيل المثال، استخدم البطاقة 4111 1111 1111 1111 مع CVV 737 لاختبارات Visa. قم بتمكين طرق الدفع مثل iDEAL أو Klarna في لوحة التحكم. تضمن هذه الخطوة أن تكاملك يدعم التفضيلات الإقليمية.
علاوة على ذلك، ميز بيئات الاختبار عن البيئات الحية. تستخدم عناوين URL الاختبارية test.adyen.com، بينما تتضمن العناوين الحية بادئة فريدة مثل [عشوائي]-[الشركة]. تنصح Adyen بالبدء في وضع الاختبار لتجنب الرسوم.
بعد الإعداد، احصل على بيانات الاعتماد لمصادقة الطلبات.
كيفية الحصول على بيانات اعتماد واجهة برمجة التطبيقات (API) ومفتاح العميل (Client Key)؟
تقوم بإنشاء مفاتيح واجهة برمجة التطبيقات في منطقة العملاء تحت المطورون > بيانات اعتماد واجهة برمجة التطبيقات. اختر بيانات اعتماد على مستوى التاجر، مثل ws@Company.[YourCompanyAccount]. أنشئ مفتاحًا جديدًا إذا لم يكن موجودًا.
يشبه مفتاح واجهة برمجة التطبيقات Aq42_... ويمنح حق الوصول إلى نقاط النهاية. انسخه بأمان، حيث لن تعرضه Adyen مرة أخرى. بعد ذلك، أنشئ مفتاح عميل (Client Key) في نفس الصفحة لمصادقة جانب العميل، مسبوقًا بـ test_ أو live_.
أضف الأصول المسموح بها، مثل http://localhost:8080، لمنع مشاكل CORS. احفظ التغييرات. تمكّن هذه المفاتيح الاستدعاءات من جانب الخادم ومكونات الواجهة الأمامية مثل Drop-in.
قم بتخزين المفاتيح في متغيرات البيئة أو ملفات التكوين، وليس أبدًا في مستودعات الكود. بالنسبة لتطبيقات Java، قم بحقنها عبر ملفات الخصائص. تعزز هذه الممارسة الأمان.
مع جاهزية بيانات الاعتماد، استكشف المصادقة.
ما هي طرق المصادقة لواجهة برمجة تطبيقات Adyen؟
تستخدم Adyen مفاتيح واجهة برمجة التطبيقات (API) للمصادقة الأساسية. قم بتضمين المفتاح في رأس X-API-Key لطلبات جانب الخادم. على سبيل المثال:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
يستخدم جانب العميل مفتاح العميل (Client Key) لتهيئة المكتبات مثل Adyen.Web. وهذا يفصل الاهتمامات، مما يقلل من التعرض.
تتطلب Webhooks التحقق من HMAC. توقع Adyen الإشعارات باستخدام مفتاح HMAC، والذي تتحقق منه باستخدام المكتبات. تشير التوقيعات غير الصالحة إلى التلاعب.
بالإضافة إلى ذلك، تدعم بعض نقاط النهاية رموز Bearer لـ OAuth، لكن مفاتيح واجهة برمجة التطبيقات كافية لمعظم عمليات التكامل. استخدم دائمًا HTTPS لتشفير عمليات الإرسال.
تؤدي المصادقة غير الصحيحة إلى أخطاء 401. لذلك، اختبر بيانات الاعتماد مبكرًا.
الآن، افحص نقاط النهاية الأساسية.
استكشاف نقاط النهاية الرئيسية في واجهة برمجة تطبيقات Adyen
تنظم واجهة برمجة تطبيقات Adyen نقاط النهاية حسب الوظيفة. تسترد نقطة النهاية /paymentMethods الطرق المتاحة بناءً على الموقع والعملة. أرسل طلب POST مع merchantAccount:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
تدرج الاستجابة طرقًا مثل البطاقات أو iDEAL.
تبدأ نقطة النهاية /payments المعاملات. قم بتضمين amount وpaymentMethod وreference:
{
"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"
}
تتضمن الاستجابات الناجحة resultCode مثل Authorised.
للحصول على التفاصيل، استخدم /payments/details لتقديم بيانات إضافية، مثل نتائج 3DS.
تتعامل نقاط نهاية واجهة برمجة التطبيقات Recurring مثل /recurring مع بيانات الاعتماد المخزنة. تدير واجهة برمجة التطبيقات Payouts تحويلات الأموال.
يبسط Apidog استكشاف هذه الواجهات عن طريق استيراد المجموعات، مما يتيح تعديل المعلمات والتحقق من صحة الاستجابة.
للانتقال إلى التنفيذ، اتبع هذه الخطوات.
دليل خطوة بخطوة: دمج واجهة برمجة تطبيقات Adyen في تطبيقك
يدمج المطورون واجهة برمجة تطبيقات Adyen باستخدام مكونات جانب الخادم وجانب العميل. ابدأ بإطار عمل خلفي مثل Java Spring Boot.
أولاً، أضف مكتبة Adyen. في build.gradle:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
قم بتكوين العميل:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
في الواجهة الأمامية، قم بتضمين 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">
جلب طرق الدفع:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
تهيئة 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');
للمدفوعات، أنشئ نقطة نهاية خلفية:
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 بإضافة browserInfo و origin. إذا كان action.type هو redirect، أعد توجيه المستخدم.
بالنسبة لـ webhooks، قم بإعداد نقطة نهاية لاستقبال طلبات POST. تحقق من HMAC:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
مكّن طرقًا محددة في لوحة التحكم. لـ iDEAL:
أضف اختيار المصدر في paymentMethod.
بالنسبة لـ Klarna، قم بتضمين lineItems:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
اختبر باستخدام امتداد بطاقة Adyen أو المدخلات اليدوية.
يدعم هذا التكامل التدفقات الأساسية. قم بالتوسيع لترميز البيانات (tokenization): قم بتخزين التفاصيل باستخدام /payments، مع تعيين storeDetails: true.
يتم التقاط التفويض المسبق لاحقًا عبر /captures.
يساعد Apidog عن طريق محاكاة الاستجابات واختبار الحالات الهامشية.
كيفية استخدام Apidog لاختبار واجهة برمجة تطبيقات Adyen؟
يبسط Apidog اختبار واجهة برمجة تطبيقات Adyen. قم بتنزيل الإصدار المجاني واستورد مجموعة Adyen.
على سبيل المثال، الصق cURL لـ /adjustAuthorisation:
يقوم Apidog بتحليله، ويملأ الحقول. أرسل لعرض الاستجابات.
اختبار التدفقات: التفويض، ثم الالتقاط (capture). استخدم التأكيدات لرموز الحالة.
يقوم Apidog بمحاكاة نقاط النهاية، محاكاة التأخيرات أو الأخطاء. ادمج مع CI/CD للتشغيل التلقائي.
بالنسبة لـ Adyen، تحقق من الأمان مثل 3DS عن طريق ربط الطلبات.
بالإضافة إلى ذلك، قم بإنشاء وثائق من المواصفات، وشاركها مع الفرق.
تقلل هذه الأداة من الجهد اليدوي، وتكتشف المشاكل مبكرًا.
أفضل الممارسات لاستخدام واجهة برمجة تطبيقات Adyen
نفذ مفاتيح تحقيق التماثل (idempotency keys) لمنع التكرار: قم بتعيين UUID في RequestOptions.
استخدم تدفقات الجلسات (sessions flow) للأمان من جانب العميل، مع إنشاء الجلسات من جانب الخادم.
راقب الأداء باستخدام webhooks، وسجل الأحداث.
التزم بمعيار PCI DSS بتجنب تخزين البيانات الحساسة.
قم بالتوسع عن طريق تجميع المدفوعات.
علاوة على ذلك، قم بتحديث المكتبات بانتظام للحصول على الميزات.
المشاكل الشائعة واستكشاف الأخطاء وإصلاحها
401 غير مصرح به: تحقق من مفتاح واجهة برمجة التطبيقات.
HMAC غير صالح: تحقق من تطابق المفتاح.
مدفوعات مرفوضة: استخدم بطاقات الاختبار بشكل صحيح.
أخطاء CORS: أضف الأصول.
راجع السجلات في منطقة العملاء.
الميزات المتقدمة: 3D Secure، وWebhooks، والمزيد
مكّن 3DS الديناميكي: عيّن attemptAuthentication: always.
تقوم Webhooks بالإخطار بشكل غير متزامن—تعامل مع أحداث AUTHORISATION.
للمنصات، استخدم /transfers.
دمج BinLookup للرسوم.
يختبر Apidog هذه السيناريوهات.
الخاتمة
أصبحت الآن تعرف كيفية الوصول إلى واجهة برمجة تطبيقات Adyen واستخدامها بفعالية. من الإعداد إلى عمليات الدمج المتقدمة، يزود هذا الدليل المطورين بالمعرفة اللازمة. جرب في وضع الاختبار، ثم انتقل إلى الوضع الفعلي. أدوات مثل Apidog تسرّع العملية.