الدروسكيف تقبل دفعة مالية على موقعك

درس مصغّر 26 من 30 · تشغيل موقعك وصيانته

اختر هدفًا للدفع التجريبي

لمن هذا الدرس؟

لمن يريدون زر دفع في موقع. يستخدم المسار الأساسي صفحة دفع مستضافة ومساعد برمجة لربطها؛ أما كود الخادم وإعداد قاعدة البيانات وبرمجة webhook فهي أعمال متقدمة اختيارية.

ابدأ بصفحة دفع مستضافة بدل جمع تفاصيل البطاقات بنفسك.

هدف هذا الدرس

  • أنشئ رابط دفع واضحًا بأنه تجريبي داخل بيئة الاختبار.
  • اربط زر الدفع في الموقع واختبره.
  • تحقق لدى المزود من حالتي السداد المؤكد والإلغاء الفعليتين بدل الوثوق بصفحة العودة.
شرح ومثال محلول وتدريب

قبل أن تبدأ

تحتاج إلى حساب Stripe مؤهل تملكه، مع بيئة sandbox أو اختبار، والصفحة المرفقة. يستطيع مساعد البرمجة ضبط رابط الاختبار العام. لا يحتاج المسار الأساسي إلى Supabase أو مفتاح API سري في المتصفح أو خادم مخصص.

تحقّق من مهارات البداية

هذه مهارات مفيدة وليست دروسًا إلزامية تمنع الدخول. ابدأ هنا إن كنت تتقنها، وإلا افتح التحضير المرتبط. ملفات البداية مرفقة، فلا تحتاج إلى موقع شخصي سابق.

  1. كيف تنشر موقعك من GitHub

    اربط مستودعًا تجريبيًا بالاستضافة.

الوقت المتوقع: 35–53 دقيقة

تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. أهلية الحساب وتفعيله وإطلاق عمل حقيقي خارج هذا المختبر. لا تُستخدم أموال حقيقية أو تفاصيل بطاقات حقيقية.

افهم الفكرة

استخدم بيئة اختبار Stripe الخاصة بك ومنتجًا وسعرًا وهميين. افتح الصفحة المرفقة مع مساعدك وحدّد ما ينبغي أن يصفه زر الدفع.

أبقِ هذا التمرين في وضع الاختبار. فتح الزائر عنوان نجاح لا يثبت وقوع دفع.

مثال عملي

للتوضيح، قد يكون المنتج Sample digital workshop بسعر اختبار لمرة واحدة قدره 5 دولارات أمريكية. ينبغي أن يوضح الزر أنه يفتح دفعًا تجريبيًا؛ ولا تعد الصفحة أو هذا الدرس بالتسليم التلقائي للمنتج.

استخدم الصفحة العامة المرفقة لتمرين Payment Link مستضاف أساسي. ساعدني في إنشاء منتج وسعر تجريبيين في بيئة Stripe التجريبية الخاصة بي، ووضع رابط الدفع التجريبي العام فقط في إعداد الصفحة. لا تضبط مسار قاعدة البيانات أو webhook الاختياري، ولا تستخدم بيانات تشغيل فعلي. ساعدني في نشر صفحة التدريب المقصودة وحدها والتحقق من دفعة تجريبية في لوحة المزود. صفحة العودة ليست دليل دفع.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

فحص الملفات منفردة (اختياري)

جرّب بنفسك

أي عنصر وسعر تجريبيين سيصفهما الزر؟ وأين ستتحقق من الدفع؟

عرض حل نموذجي مشروح

منتجي التوضيحي هو Sample digital workshop بسعر USD 5 في بيئة اختبار Stripe. يفتح الزر صفحة الدفع التجريبية المستضافة. سأتحقق من حالة السداد والمبلغ والعملة للدفعة المطابقة في حساب Stripe؛ فزيارة success.html لا تثبت الدفع.

ما تتضمنه الإجابة السليمة

  • يحدد منتجًا تجريبيًا خياليًا ومبلغًا وعملة.
  • يحدد سجل الدفع لدى المزود مكانًا للتحقق من السداد.
كيف يعمل؟ (اختياري)

اقبل دفعة اختبار عبر صفحة دفع مستضافة

ابدأ بصفحة اختبار يستضيفها المزوّد وحد نجاح واضح التعريف.

يتيح Payment Link مستضاف للمزوّد جمع تفاصيل الدفع دون وضع حقول بطاقة في صفحتك. لا يستخدم هذا التدريب إلا بيئة Stripe التجريبية وقيم بطاقات الاختبار.

يفتح الموقع صفحة الدفع، بينما يتلقى الخادم أحداث دفع موقعة ويسجّل إيصالًا. صفحة العودة تنقل فقط: يستطيع أي شخص فتح رابط، لذا لا يثبت وجودها الدفع.

مثال محلول

يجب ألا ينشئ فتح success.html مباشرة إيصالًا. يمكن لجلسة مدفوعة متحقق منها من Payment Link الاختباري المعدّ إنشاء إيصال حتى إن لم يعد العميل إلى موقعك.

Stripe: بعد الدفع عبر Payment Link · Stripe: الاختبار

تمرين تقني إضافي

يزور مستخدم /success.html?paid=true. هل ينبغي أن يمنحه نظامك منتجًا مدفوعًا؟

عرض حل نموذجي مشروح

لا. يتحكم الزائر بمعامل الاستعلام. استخدم حدث مزوّد متحققًا منه أو فحص مزوّد في الخادم مرتبطًا بالمعاملة المقصودة.

  • ترفض الروابط التي يتحكم بها مقدم الطلب دليلًا على الدفع.
  • تشترط حالة دفع متحققًا منها لدى المزوّد.

الخطوة 1 · كيف تقبل دفعة مالية على موقعك

أنشئ رابط الاختبار واربطه

استخدم لوحة المزود ودع المساعد يعدّل الصفحة.

شرح ومثال محلول وتدريب

افهم الفكرة

أنشئ المنتج والسعر التجريبيين للدفع مرة واحدة وPayment Link في حسابك. افتح صفحة الدفع العامة دون دخول، ثم أعطِ رابط الاختبار للمساعد ليربطه بالصفحة العامة المرفقة.

افحص العنصر والمبلغ والعملة وبيئة الاختبار قبل المتابعة. رابط الدفع التجريبي العام وحده هو ما يوضع في هذه الصفحة؛ لا يحتاج الرابط الأساسي إلى مفتاح توقيع أو API خاص.

مثال عملي

يفتح الإعداد الناجح صفحة الدفع التجريبية العامة للمنتج دون تسجيل دخول. صفحة إعدادات حساب Stripe أو القيمة المؤقتة test_REPLACE دون تغيير ليست رابط دفع قابلًا للاستخدام.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

فحص الملفات منفردة (اختياري)

جرّب بنفسك

هل يفتح زر الموقع صفحة الدفع التجريبية المقصودة بالعنصر والسعر الصحيحين؟

عرض حل نموذجي مشروح

مثال فحص: يفتح رابط الموقع دفعًا تجريبيًا عامًا لمنتج Sample digital workshop بسعر USD 5 دون طلب دخول حسابي في Stripe. الرابط التجريبي العام وحده مُعدّ في الصفحة؛ ولا يلزم مفتاح API أو سر webhook لهذا المسار الأساسي.

ما تتضمنه الإجابة السليمة

  • يقارن الدفع المستضاف دون دخول بالمنتج والمبلغ والعملة ووضع الاختبار المقصودين.
  • يضع رابط Payment Link التجريبي العام وحده في إعداد الصفحة المرفقة.
كيف يعمل؟ (اختياري)

اضبط صفحة الدفع الاختبارية المنفصلة

افصل روابط الدفع العامة عن بيانات اعتماد الخادم وأسرار webhook.

اتبع START-HERE.txt لإنشاء Payment Link اختباري لمرة واحدة وجدول قاعدة بيانات ووجهة webhook. ثبّت تبعية Stripe المحددة الإصدار في مشروع التدريب واحتفظ بملف القفل الناتج.

ضع رابط الدفع الاختباري العام فقط في config.js. تتضمن قيم بيئة الخادم مفتاح الاختبار السري وسر توقيع نقطة النهاية ومعرّف Payment Link المتوقع ومفتاح قاعدة البيانات الخاص. ترفض هذه الشيفرة عمدًا بيانات الاعتماد الفعلية.

للتسلسل المحلي الكامل، افتح run-locally.txt: جهز بيئة الجذر الخاصة، واربط مشروع التدريب فقط، وابدأ وكيل دوال Netlify. يسرد server-env.example.txt أسماء المتغيرات دون أسرار حقيقية. فتح HTML وحده لا يشغّل الخادم.

مثال محلول

يثبت سر توقيع webhook أحداث أي نقطة نهاية تقبلها. ليس هو Payment Link العام ولا مفتاح API؛ نسخ السر الخاطئ يسبب فشل توقيع.

Node.js: حالة دعم الإصدارات

تمرين تقني إضافي

أيهما مكانه public/config.js: رابط الدفع الاختباري أم سر توقيع whsec؟

عرض حل نموذجي مشروح

رابط الدفع العام فقط مكانه هناك. أبقِ سر webhook ومفاتيح المزوّد وقاعدة البيانات السرية في متغيرات بيئة الخادم.

  • تُبقي أسرار التوقيع وAPI في الخادم.
  • تستخدم وجهة الدفع العامة فقط في شيفرة المتصفح.

الخطوة 2 · كيف تقبل دفعة مالية على موقعك

أكمل دفعة تجريبية واحدة لدى المزود

استخدم تعليمات الاختبار الرسمية وافحص نتيجة الحساب.

شرح ومثال محلول وتدريب

افهم الفكرة

اتبع دليل اختبار Stripe المرتبط داخل بيئة الاختبار فقط. أكمل عملية دفع تجريبية، ثم اعثر على دفعتها أو جلستها الفعلية في حسابك.

تحقق هناك من المبلغ والعملة المتوقعين ومن أن الحالة تؤكد السداد (paid). قد يختلف اكتمال مسار الصفحات عن الحالة النهائية للدفع، خصوصًا لطرق تُسوّى لاحقًا.

مثال عملي

«انتهت خطوات الدفع» و«تأكد سداد الدفعة» ليستا دائمًا الملاحظة نفسها.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

    فحص الملفات منفردة (اختياري)

    جرّب بنفسك

    ماذا أفاد سجل المزود فعلًا بشأن دفعتك التجريبية؟

    عرض حل نموذجي مشروح

    مثال نتيجة مزود: الدفعة التجريبية المطابقة مسددة بمبلغ USD 5، وهو السعر التجريبي المختار. إذا عرض المزود بدلًا من ذلك أنها قيد المعالجة أو غير مسددة، فسأسجل تلك الحالة، لا أعد الطلب مدفوعًا لأن صفحة الدفع انتهت.

    ما تتضمنه الإجابة السليمة

    • يعثر على الدفعة التجريبية المطابقة وحالة سدادها الفعلية في حساب المزود.
    • يقارن المبلغ والعملة المسجلين بسعر الاختبار المختار.
    كيف يعمل؟ (اختياري)

    تحقق من الحدث وسجّل حالة الدفع مرة واحدة

    صادِق الحمولة الخام قبل تفسير JSON الخاص بها.

    يمرر المعالج بايتات الطلب الخام غير المتغيرة وStripe-Signature إلى SDK الرسمية. قد يغير تحليل JSON أو إعادة تنسيقه قبل التحقق من التوقيع تلك البايتات ويعطّل التحقق.

    لا يقبل إلا أنواع الأحداث المتوقعة ووضع الاختبار وpayment_link المطابق وpayment_status=paid. قد تكمل طرق مؤجلة صفحة الدفع قبل نجاح الدفع، لذا لا يكفي اكتمال الصفحة وحده. تجعل session_id فريدة تكرار إدراج الإيصال بلا أثر ضار.

    قد يصف معرّفا حدث مختلفان جلسة الدفع نفسها: مثل اكتمال الصفحة ثم نجاح الدفع غير المتزامن. يجعل المفتاح الأساسي session_id مع on_conflict=session_id وresolution=ignore-duplicates إدراج الإيصال الدائم قابلًا للتكرار. لا يُبتلع فشل كتابة قاعدة البيانات: يعيد 503 كي يُعاد تسليم الحدث.

    مثال محلول

    تظل للجلسة المدفوعة نفسها المسلّمة مرتين قيمة مفتاح أساسي واحدة. يعيد فشل قاعدة البيانات 503 كي يعاد التسليم، بدل تأكيد حدث ضاعت نتيجته.

    Stripe: التحقق من توقيع webhook وإعادة المحاولات

    تمرين تقني إضافي

    لماذا لا يمكن اعتبار checkout.session.completed مع payment_status=unpaid طلبًا مدفوعًا بعد؟

    عرض حل نموذجي مشروح

    تؤكد بعض طرق الدفع لاحقًا. انتظر حالة مدفوعة متحققًا منها، بما في ذلك حدث النجاح غير المتزامن حيث ينطبق، قبل تسجيل إيصال مدفوع.

    • تفصل اكتمال صفحة الدفع عن حالة دفع مسوّاة.
    • تنتظر التأكيد المناسب للدفع.

    الخطوة 3 · كيف تقبل دفعة مالية على موقعك

    جرّب الإلغاء وفتح صفحة العودة مباشرة

    تحقق أن الزائر لا يستطيع اصطناع نتيجة دفع بالتنقل بين الصفحات.

    شرح ومثال محلول وتدريب

    افهم الفكرة

    ابدأ دفعًا تجريبيًا منفصلًا واتركه دون إكمال السداد، أو استخدم مسار إلغاء توفره الصفحة المستضافة فعلًا. وافتح بصورة منفصلة صفحة success.html المرفقة مباشرةً. قارن الحالتين بسجلات الدفع التجريبية لدى المزود.

    قد يبقى الدفع المتروك غير مكتمل أو مفتوحًا بدل أن يحمل حرفيًا حالة canceled. ولا ينبغي الإبلاغ عن أي من الإجراءين كشراء جديد مسدد. الصفحة الأساسية لا تسلّم المنتج تلقائيًا.

    مثال عملي

    فتح success.html أو إضافة paid=true إلى رابطها لا ينشئ دفعة مسددة مطابقة في Stripe. العودة إلى الموقع وإثبات الدفع عمليتان منفصلتان.

    ملفات هذه الخطوة

    ابدأ هناملفات ورشة العمل

    افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

      فحص الملفات منفردة (اختياري)

      جرّب بنفسك

      ماذا أثبت الإلغاء وفتح صفحة العودة مباشرة؟ وما الذي لم يثبتاه؟

      عرض حل نموذجي مشروح

      في هذا الفحص التوضيحي، تُرك الدفع الثاني غير مكتمل ولم تنشأ دفعة مسددة جديدة. عرض فتح success.html مباشرة رسالة العودة فقط. لا يثبت أي إجراء عملية شراء، ولا تمنح الصفحة الأساسية وصولًا تلقائيًا إلى المنتج.

      ما تتضمنه الإجابة السليمة

      • يميز الدفع الملغى أو غير المكتمل عن دفعة مطابقة مسددة.
      • يدرك أن فتح صفحة العودة مباشرةً لا يثبت الدفع أو يمنح التسليم.
      كيف يعمل؟ (اختياري)

      تتبّع دفعة اختبار واحدة من البداية للنهاية

      طابق جلسة الدفع والحدث الموقع والإيصال المخزن.

      استخدم قيم بطاقات الاختبار الرسمية فقط في صفحة الدفع التجريبية. اعثر على الجلسة الناتجة وتسليم webhook في حسابك، ثم افحص جدول payment_receipts الخاص في مشروع التدريب.

      تحقق من المبلغ والعملة مقابل تلك الجلسة. أعد إرسال الحدث المشروع نفسه وأكد بقاء صف واحد. جرّب طلبًا غير موقع وزيارة مباشرة لصفحة النجاح؛ يجب ألا ينشئ أي منهما سجل دفع.

      مثال محلول

      تثبت استجابة webhook بالحالة 200 أن المعالج أقر شيئًا. افحص الإيصال والجلسة المطابقين بدل افتراض أن كل الأحداث تخص المنتج المقصود.

      تمرين تقني إضافي

      يعيد webhook الحالة 200 لحدث غير مرتبط. هل يعني ذلك وجوب وجود إيصال؟

      عرض حل نموذجي مشروح

      لا. يقر المعالج الأحداث المتجاهلة دون إيصال. يجب ألا تنشئ السجل المقصود إلا جلسة اختبار مدفوعة مطابقة.

      • تفهم الأحداث المتجاهَلة عمدًا.
      • تطابق الحالة المخزنة بالجلسة المدفوعة المحددة.

      الخطوة 4 · كيف تقبل دفعة مالية على موقعك

      سلّم مسار الدفع الأساسي

      أكمل رابطًا مفيدًا دون الادعاء بوجود نظام تجارة متكامل.

      شرح ومثال محلول وتدريب

      افهم الفكرة

      كرّر فحص زر الموقع والدفع التجريبي بعد أي إصلاح. احفظ صفحة التدريب ورابطها وسجلًا للمحاولات الناجحة والملغاة أو غير المكتملة، بعد إزالة المعلومات الحساسة.

      قبل المبيعات الحقيقية، تحقق من أهلية نشاطك وحسابك والسعر والعملة والشروط وطريقة التشغيل. الوصول التلقائي والأحداث الموقّعة واستعادة قاعدة البيانات ضمن المادة المتقدمة الاختيارية أدناه.

      مثال عملي

      زر دفع مستضاف يعمل نتيجة صغيرة صالحة؛ لكنه لا يثبت وجود نظام خلفي لتسليم المنتج لم يُبنَ بعد.

      ملفات هذه الخطوة

      ابدأ هناملفات ورشة العمل

      افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

      فحص الملفات منفردة (اختياري)

      جرّب بنفسك

      قدّم مسار الاختبار والنتائج الفعلية في البيئة التجريبية وما يلزم قبل إطلاق حقيقي.

      ما المطلوب إنجازه: رابط أو صفحة الدفع التجريبي والملاحظات الفعلية للدفع والإلغاء في البيئة التجريبية، دون تحصيل حقيقي.

      عرض حل نموذجي مشروح

      مثال تسليم: تفتح الصفحة الدفع التجريبي للورشة بسعر USD 5؛ وتوجد دفعة تجريبية مطابقة مسددة بقيمة USD 5؛ والمحاولة المتروكة غير مدفوعة؛ وفتح صفحة العودة مباشرةً لا يغير أي سجل. لم يُختبر خصم حقيقي أو تسليم منتج تلقائي. قبل الإطلاق الفعلي، ما زلت بحاجة إلى حساب مؤهل وشروط حقيقية وعملية تسليم متحقق منها.

      ما تتضمنه الإجابة السليمة

      • يقدم المسار التجريبي العام المُعدّ ونتائج السداد وعدم الإكمال أو الإلغاء.
      • يوضح أن الخصم الحقيقي والتسليم التلقائي خارج الاختبار الأساسي المكتمل.
      كيف يعمل؟ (اختياري)

      مهمتك: تدرّب على التعافي دون رسوم حقيقية

      يجب أن يتعافى مسار الدفع من كتابة قاعدة بيانات فائتة.

      في المشروع القابل للاستغناء عنه، استخدم إعداد قاعدة بيانات غير صحيح مؤقتًا وأعد إرسال حدث اختبارك المدفوع المشروع. لاحظ استجابة غير ناجحة وعدم وجود إيصال جديد. استعد الإعداد وأعد الإرسال، ثم تحقق من صف مطابق واحد بالضبط.

      اشرح ما يتبقى قبل البيع الحقيقي: إعداد حساب وعمل مدعوم، وسعر وعملة وشروط صحيحة، وتنفيذ دائم للطلبات، وتسوية ومبالغ مستردة ومراقبة تشغيلية. تسجّل هذه الورشة إيصالات اختبار فقط.

      مثال محلول

      إذا فشل التخزين لكن نقطة النهاية قالت «نجاح»، فقد تتوقف إعادة المحاولات التلقائية قبل وجود سجلك. الفشل الصادق جزء من معالجة دفع موثوقة.

      يتوفر الشرح المرجعي الكامل في reference/assignment-walkthrough.txt. قارن خطواته بنتيجتك؛ واملأ سجل الاختبار بملاحظات من مشروعك أنت.

      تمرين تقني إضافي

      أظهر محاولة تخزين فاشلة وتعافيًا ناجحًا آمنًا من التكرار.

      عرض حل نموذجي مشروح

      ثبّت التبعيات في مشروع التدريب المنفصل باستخدام npm install؛ ينشئ ذلك package-lock.json، واحتفظ به مع المشروع. استخدم Payment Link اختباريًا وبيانات اعتماد sk_test_ فقط. الرابط العام ليس سر توقيع webhook.

      اعثر على جلسة اختبارك المدفوعة المطابقة وتسليم webhook الموقع وإيصال خاص يطابق session_id والمبلغ والعملة. أعد تسليم الحدث: يجب أن يترك المفتاح الأساسي وتفضيل ignore-duplicates إيصالًا واحدًا. يجب ألا ينشئ طلب غير موقع أو زيارة مباشرة لصفحة النجاح أي إيصال.

      للتدرب على الفشل، غيّر SUPABASE_URL مؤقتًا في البيئة المحلية أو الخادم القابلة للاستغناء عنها فقط إلى هدف اختبار غير صحيح. أعد تسليم الحدث المشروع نفسه ولاحظ فشلًا قابلًا لإعادة المحاولة. استعد الإعداد وأعد التسليم وتحقق من إيصال دائم واحد. لا تغيّر إعدادات الإنتاج أو تختبر ببطاقة حقيقية أبدًا.

      • لا يقر فشل الحفظ الدائم بنجاح المعالجة.
      • ينشئ التعافي إيصالًا واحدًا؛ ولا تُستخدم تفاصيل دفع أو أموال حقيقية.

      هل أفادك هذا الدرس؟

      اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.