انتقل إلى المقال
Aniq-UI

E-Commerceالمدفوعات

المدفوعات

كيف تستلم صفحة إتمام الشراء الدفع، وكيف تربط Stripe، وما الذي يحدث للطلب في كل خطوة.

لحزمة الحزمة الكاملة

كيف تستلم صفحة إتمام الشراء الدفع

يقدّم المتجر طريقتين للدفع: البطاقة عبر Stripe، والدفع عند الاستلام. لا يوجد خيار PayPal في صفحة إتمام الشراء. كلتاهما تنشئ الطلب في واجهة API أولًا، بسعر تحدده واجهة API من الكتالوج الخاص بها، لا من الأسعار التي يرسلها المتصفح أبدًا.

الطريقةما يحدث للطلب
البطاقة (Stripe)يُحفظ بالحالة pending وغير مدفوع. تطلب واجهة API من Stripe عملية دفع، ويؤكد المتجر البطاقة في الصفحة نفسها. عندما يُبلغ Stripe عن الدفع عبر webhook، يصبح الطلب paid وconfirmed؛ والبطاقة المرفوضة تجعله failed.
الدفع عند الاستلاميُحفظ بالحالة confirmed وغير مدفوع فورًا. تحصّل المبلغ عند التسليم وتنقل الطلب إلى المرحلة التالية في لوحة الإدارة.

الدفع عند الاستلام هو الخيار المحدد افتراضيًا. يستطيع الضيوف إتمام الشراء ببريدهم الإلكتروني؛ ويرى العملاء المسجّلون الطلب في حساباتهم.

الشحن مجاني ابتداءً من 75 دولارًا، ويكلّف 9.99 دولار لما دون ذلك، ولا توجد ضريبة. تطبّق السلة وملخص إتمام الشراء وواجهة API القاعدة نفسها، فيكون المبلغ الذي يراه المتسوّق هو المبلغ المحصَّل. يحفظ المتجر القاعدة في storefront/src/config/shipping.ts وواجهة API في back-end/src/modules/orders/orders.service.ts: غيّرهما معًا. يحصّل Stripe المبالغ بالدولار الأمريكي.

اربط Stripe

  1. أضف مفاتيح API الخاصة بك

    من صفحة مفاتيح API في لوحة تحكم Stripe، ضع المفتاح السري في back-end/.env. استخدم مفاتيح الاختبار (sk_test_…) إلى أن تكون مستعدًا لاستلام أموال حقيقية.

    back-end/.env
    STRIPE_SECRET_KEY=sk_test_…

  2. اشترك في webhook

    في Stripe، أضف نقطة نهاية webhook على عنوان واجهة API الخاصة بك متبوعًا بـ /api/payments/webhook، مشتركة في payment_intent.succeeded وpayment_intent.payment_failed. انسخ سر التوقيع الخاص بها إلى back-end/.env.

    back-end/.env
    STRIPE_WEBHOOK_SECRET=whsec_…

  3. أعطِ المتجر مفتاحه القابل للنشر

    اضبط المفتاح القابل للنشر في ملف .env الخاص بالمتجر، ثم أعد بنائه: المفتاح يُضمَّن أثناء البناء. ومع Docker Compose، ضعه في ملف .env بجوار docker-compose.yml وشغّل docker compose up --build.

    storefront/.env
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_…

  4. أعد تشغيل واجهة API

    النتيجة المتوقعة: يكتب سجل واجهة API الرسالة "Stripe initialized"، وتعرض صفحة إتمام الشراء نموذج البطاقة.

الـ webhook هو ما يعلّم الطلب كمدفوع

يُعلَّم الطلب كمدفوع عندما يستدعي Stripe الـ webhook، لا عندما يعود المتسوّق من صفحة الدفع. من دون الاشتراك وسر التوقيع الخاص به، تبقى طلبات البطاقة معلّقة وغير مدفوعة.

لاختبار الـ webhook على جهازك، تستطيع أداة Stripe CLI تمرير الأحداث إلى http://localhost:8000/api/payments/webhook، وتطبع سر التوقيع الذي تستخدمه أثناء عملها.

من دون Stripe

  • من دون NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY، أو مع أي قيمة ليست مفتاحًا حقيقيًا pk_test_… أو pk_live_…، يعرض خيار البطاقة في صفحة إتمام الشراء الرسالة «الدفع بالبطاقة غير متاح حالياً. يرجى اختيار الدفع عند الاستلام.» ويُخفي حقل البطاقة.
  • من دون STRIPE_SECRET_KEY، أو مع القيمة المؤقتة الموجودة في .env.example، لا تقبل واجهة API أي دفع بالبطاقة: الطلب المُنشأ بطريقة البطاقة يُحفظ معلّقًا وغير مدفوع.
  • الدفع عند الاستلام يعمل في الحالتين.
  • على المتجر النموذجي في المتجر، ومن دون أي واجهة API، تكتمل عملية إتمام الشراء دون الاتصال بـ Stripe ولا يُحصَّل أي مبلغ.

استلام مدفوعات حقيقية

  • استبدل المفاتيح بالمفاتيح المباشرة (sk_live_… وpk_live_…) وبـ webhook مُنشأ في الوضع المباشر، وله سر توقيع خاص به.
  • اضبط NEXT_PUBLIC_DEMO_CHECKOUT=false، حتى لا تُملأ صفحة إتمام الشراء مسبقًا ببيانات مشترٍ مولَّد.
  • تُحصَّل الأسعار بالدولار الأمريكي. للبيع بعملة أخرى، غيّر العملة التي ترسلها واجهة API إلى Stripe في back-end/src/modules/payments/payments.service.ts، واضبط NEXT_PUBLIC_ANALYTICS_CURRENCY بما يطابقها.

توقفت عند خطوة؟

ابحث عن الحل قبل أن تبدأ من جديد.

حل المشكلات

تفضيلات ملفات تعريف الارتباط

نستخدم ملفات تعريف الارتباط لتعزيز تجربة التصفح الخاصة بك وتحليل حركة المرور على الموقع وتخصيص المحتوى. بالنقر على "قبول الكل"، فإنك توافق على استخدامنا لملفات تعريف الارتباط للتحليلات والإعلانات المخصصة.