تكامل بوابة الدفع Square: دليل المطور الكامل لتطبيقات الويب

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

1. متى تختار Square
2. إعداد Web Payments SDK
3. التكامل من جانب الخادم
4. تنفيذ مكون React
5. تكامل المحافظ الرقمية
6. اعتبارات القنوات المتعددة

متى تختار Square

Square هو الاختيار الصحيح عندما:

• البيع بالتجزئة متعدد القنوات - تحتاج مدفوعات موحدة عبر الإنترنت وشخصياً
• الأعمال الصغيرة والمتوسطة - تسعير شفاف، بدون رسوم شهرية
• إعداد سريع - وقت أسرع للسوق من الحلول المؤسسية

التكامل من جانب الخادم

export class SquarePaymentService {
  async createPayment(params: CreatePaymentParams) {
    const { result } = await squareClient.paymentsApi.createPayment({
      sourceId: params.sourceId,
      idempotencyKey: `${params.orderId}-${Date.now()}`,
      amountMoney: {
        amount: BigInt(params.amount),
        currency: params.currency,
      },
      locationId: SQUARE_CONFIG.locationId,
      referenceId: params.orderId,
      autocomplete: true,
    });

    return {
      paymentId: result.payment!.id!,
      status: result.payment!.status!,
    };
  }
}

تنفيذ مكون React

export function SquarePayment({ applicationId, locationId, onSuccess, onError }) {
  const [card, setCard] = useState(null);

  useEffect(() => {
    async function init() {
      const payments = window.Square.payments(applicationId, locationId);
      const cardInstance = await payments.card();
      await cardInstance.attach('#card-container');
      setCard(cardInstance);
    }
    init();
  }, []);

  const handlePayment = async () => {
    const tokenResult = await card.tokenize();
    if (tokenResult.status === 'OK') {
      // أرسل التوكن للخادم
      const response = await fetch('/api/square/create-payment', {
        method: 'POST',
        body: JSON.stringify({ sourceId: tokenResult.token }),
      });
      onSuccess(await response.json());
    }
  };

  return (
    <div>
      <div id="card-container" />
      <button onClick={handlePayment}>ادفع الآن</button>
    </div>
  );
}

اعتبارات القنوات المتعددة

قوة Square هي التجارة الموحدة:

// ربط العملاء عبر الإنترنت والشخصيين
async function linkCustomerAcrossChannels(email: string) {
  const { result } = await squareClient.customersApi.searchCustomers({
    query: { filter: { emailAddress: { exact: email } } },
  });

  if (result.customers?.length > 0) {
    return result.customers[0].id;
  }

  const { result: newCustomer } = await squareClient.customersApi.createCustomer({
    emailAddress: email,
  });

  return newCustomer.customer!.id;
}

الخلاصة

Square يتفوق في:

1. البيع بالتجزئة متعدد القنوات - موحد عبر الإنترنت ونقاط البيع
2. تكامل سريع - API بسيطة، توثيق جيد
3. تسعير شفاف - بدون رسوم شهرية، معدل ثابت
4. الأعمال المركزة على أمريكا - دعم دولي محدود