دليل تكامل Adyen: تنفيذ Drop-in Component و API

جدول المحتويات

1. لماذا Adyen للمؤسسات
2. البنية للمعالجة عالية الحجم
3. التنفيذ من جانب الخادم
4. تكامل React Drop-in
5. تكوين Webhooks
6. العملات المتعددة والتوطين

لماذا Adyen للمؤسسات

Adyen هي منصة الدفع المفضلة للشركات المؤسسية مثل Uber و Spotify و Microsoft. على عكس نهج Stripe الذي يركز على المطورين، تركز Adyen على:

• منصة واحدة للمدفوعات العالمية - تكامل واحد لأكثر من 250 طريقة دفع
• الاستحواذ والمعالجة - Adyen هي المعالج والمستحوذ معاً
• إدارة مخاطر متقدمة - RevenueProtect مع كشف الاحتيال القائم على ML
• اتفاقيات مستوى خدمة للمؤسسات - وقت تشغيل مضمون ودعم مخصص

نفذت Adyen لمنصات تجارة إلكترونية تعالج أكثر من 10 ملايين يورو شهرياً.

التنفيذ من جانب الخادم

التكوين

import { Client, Config, CheckoutAPI } from '@adyen/api-library';

const config = new Config();
config.apiKey = process.env.ADYEN_API_KEY!;
config.merchantAccount = process.env.ADYEN_MERCHANT_ACCOUNT!;

const environment = process.env.NODE_ENV === 'production' ? 'LIVE' : 'TEST';

if (environment === 'LIVE') {
  config.environment = 'LIVE';
  config.liveEndpointUrlPrefix = process.env.ADYEN_LIVE_PREFIX;
}

const client = new Client({ config });
export const checkout = new CheckoutAPI(client);

إنشاء جلسات الدفع

export class AdyenPaymentService {
  async createSession(params: CreateSessionParams) {
    const sessionRequest = {
      merchantAccount: ADYEN_CONFIG.merchantAccount,
      amount: {
        value: params.amount,
        currency: params.currency.toUpperCase(),
      },
      reference: params.orderId,
      returnUrl: `${params.returnUrl}?orderId=${params.orderId}`,
      countryCode: params.countryCode,
      
      allowedPaymentMethods: ['scheme', 'applepay', 'googlepay', 'paypal'],
      
      storePaymentMethod: !!params.customerId,
      
      authenticationData: {
        threeDSRequestData: { nativeThreeDS: 'preferred' },
      },
    };

    const response = await checkout.PaymentsApi.sessions(sessionRequest);
    
    return {
      sessionId: response.id!,
      sessionData: response.sessionData!,
    };
  }
}

تكامل React Drop-in

import AdyenCheckout from '@adyen/adyen-web';

export function AdyenCheckoutComponent({ sessionId, sessionData, onPaymentCompleted }) {
  const paymentContainer = useRef(null);

  useEffect(() => {
    const initCheckout = async () => {
      const adyenCheckout = await AdyenCheckout({
        environment: 'test',
        clientKey: ADYEN_CLIENT_KEY,
        session: { id: sessionId, sessionData },
        
        paymentMethodsConfiguration: {
          card: {
            hasHolderName: true,
            holderNameRequired: true,
          },
        },
        
        onPaymentCompleted: (result) => {
          onPaymentCompleted(result);
        },
      });

      adyenCheckout.create('dropin').mount(paymentContainer.current);
    };

    initCheckout();
  }, [sessionId, sessionData]);

  return <div ref={paymentContainer} />;
}

تكوين Webhooks

التحقق من توقيع HMAC

import crypto from 'crypto';

export function verifyAdyenWebhook(body: string, hmacSignature: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', Buffer.from(ADYEN_HMAC_KEY, 'hex'))
    .update(body, 'utf8')
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(hmacSignature),
    Buffer.from(expectedSignature)
  );
}

معالج Webhook

export class AdyenWebhookService {
  async handleNotification(notification) {
    const { eventCode, merchantReference, pspReference, success } = notification;

    switch (eventCode) {
      case 'AUTHORISATION':
        await this.handleAuthorisation(notification);
        break;
      case 'CAPTURE':
        await this.handleCapture(notification);
        break;
      case 'REFUND':
        await this.handleRefund(notification);
        break;
      case 'CHARGEBACK':
        await this.handleChargeback(notification);
        break;
    }
  }
}

العملات المتعددة والتوطين

// Adyen يستخدم الوحدات الصغرى لمعظم العملات
// لكن بعض العملات ليس لها وحدات صغرى
const ZERO_DECIMAL_CURRENCIES = ['JPY', 'KRW', 'VND'];
const THREE_DECIMAL_CURRENCIES = ['BHD', 'KWD', 'OMR'];

export function toAdyenAmount(amount: number, currency: string): number {
  if (ZERO_DECIMAL_CURRENCIES.includes(currency)) return Math.round(amount);
  if (THREE_DECIMAL_CURRENCIES.includes(currency)) return Math.round(amount * 1000);
  return Math.round(amount * 100);
}

الخلاصة

Adyen قوية لكنها معقدة. النقاط الرئيسية:

1. استخدم Sessions API - النهج الحديث مع معالجة 3DS مدمجة
2. التحقق من HMAC - دائماً تحقق من توقيعات webhook
3. تعامل مع جميع رموز الأحداث - ليس فقط AUTHORISATION
4. معالجة العملات - عملات مختلفة لها أماكن عشرية مختلفة