تكامل PayPal مع React و Node.js: دليل Orders API و Smart Buttons

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

1. مكانة PayPal في استراتيجية الدفع
2. إعداد PayPal بشكل صحيح
3. تنفيذ Orders API v2
4. أزرار الدفع الذكية في React
5. تكوين Webhooks
6. المشاكل الشائعة في التكامل

مكانة PayPal في استراتيجية الدفع

PayPal ليس مجرد طريقة دفع أخرى - إنه محسّن للتحويل. من تجربتي مع منصات التجارة الإلكترونية:

• 15-30% من العملاء يفضلون PayPal على إدخال تفاصيل البطاقة
• تحسن التحويل على الجوال بشكل كبير مع الدفع بنقرة واحدة من PayPal
• تصور حماية المشتري يبني الثقة للعملاء الجدد

تنفيذ Orders API v2

إنشاء الطلبات

export class PayPalOrderService {
  async createOrder(params: CreatePayPalOrderParams) {
    const request = new checkoutNodeJssdk.orders.OrdersCreateRequest();
    request.requestBody({
      intent: 'CAPTURE',
      purchase_units: [{
        reference_id: params.orderId,
        amount: {
          currency_code: params.currency,
          value: params.amount.toFixed(2),
          breakdown: {
            item_total: { value: itemTotal.toFixed(2) },
            shipping: { value: shippingAmount.toFixed(2) },
            tax_total: { value: taxAmount.toFixed(2) },
          },
        },
        items: params.items.map(item => ({
          name: item.name.substring(0, 127),
          quantity: item.quantity.toString(),
          unit_amount: { value: item.unitAmount.toFixed(2) },
        })),
      }],
    });

    const response = await paypalClient.execute(request);
    return {
      paypalOrderId: response.result.id,
      approvalUrl: response.result.links.find(l => l.rel === 'approve')?.href,
    };
  }
}

أزرار الدفع الذكية في React

import { PayPalScriptProvider, PayPalButtons } from '@paypal/react-paypal-js';

export function PayPalPaymentButton({ orderId, onSuccess, onError }) {
  return (
    <PayPalScriptProvider options={{ clientId: PAYPAL_CLIENT_ID }}>
      <PayPalButtons
        createOrder={async () => {
          const response = await fetch('/api/paypal/create-order', {
            method: 'POST',
            body: JSON.stringify({ orderId }),
          });
          const data = await response.json();
          return data.paypalOrderId;
        }}
        onApprove={async (data) => {
          const response = await fetch('/api/paypal/capture-order', {
            method: 'POST',
            body: JSON.stringify({ paypalOrderId: data.orderID }),
          });
          const result = await response.json();
          onSuccess(result);
        }}
        onError={onError}
      />
    </PayPalScriptProvider>
  );
}

المشاكل الشائعة في التكامل

1. مشاكل دقة المبلغ

// ❌ سيء: أخطاء الفاصلة العائمة
const amount = 19.99 + 5.00; // قد يكون 24.990000000000002

// ✅ جيد: اعمل بالسنتات، حول في النهاية
const amountCents = 1999 + 500;
const paypalAmount = (amountCents / 100).toFixed(2); // "24.99"

2. التحقق من مجموع العناصر

PayPal يتحقق من أن مجموع العناصر يساوي الإجمالي.

الخلاصة

تكامل PayPal يتطلب الانتباه إلى:

1. دقة المبلغ - استخدم دائماً الحساب بالنقطة الثابتة
2. التحقق من التفصيل - العناصر يجب أن تجمع بشكل صحيح
3. موثوقية Webhook - تحقق من التوقيعات، تعامل بشكل مستقر
4. معالجة النزاعات - كن مستعداً بعملية
5. تحويل الأخطاء - أخطاء PayPal تحتاج ترجمة للمستخدمين