
درس مصغّر · العربية
كيف تقبل دفعة مالية على موقعك
أنشئ Payment Link تجريبيًا واربطه بالصفحة المرفقة، وتحقق من الدفع في حساب المزود دون بناء نظام دفع خلفي.
لمن هذا الدرس؟
لمن يريدون زر دفع في موقع. يستخدم المسار الأساسي صفحة دفع مستضافة ومساعد برمجة لربطها؛ أما كود الخادم وإعداد قاعدة البيانات وبرمجة webhook فهي أعمال متقدمة اختيارية.
قبل أن تبدأ
تحتاج إلى حساب Stripe مؤهل تملكه، مع بيئة sandbox أو اختبار، والصفحة المرفقة. يستطيع مساعد البرمجة ضبط رابط الاختبار العام. لا يحتاج المسار الأساسي إلى Supabase أو مفتاح API سري في المتصفح أو خادم مخصص.
الوقت المتوقع: 35–53 دقيقة
تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. أهلية الحساب وتفعيله وإطلاق عمل حقيقي خارج هذا المختبر. لا تُستخدم أموال حقيقية أو تفاصيل بطاقات حقيقية.
ما الذي ستتعلمه؟
- أنشئ رابط دفع واضحًا بأنه تجريبي داخل بيئة الاختبار.
- اربط زر الدفع في الموقع واختبره.
- تحقق لدى المزود من حالتي السداد المؤكد والإلغاء الفعليتين بدل الوثوق بصفحة العودة.
الخطوة 1
اختر هدفًا للدفع التجريبي
ابدأ بصفحة دفع مستضافة بدل جمع تفاصيل البطاقات بنفسك.
استخدم بيئة اختبار Stripe الخاصة بك ومنتجًا وسعرًا وهميين. افتح الصفحة المرفقة مع مساعدك وحدّد ما ينبغي أن يصفه زر الدفع.
أبقِ هذا التمرين في وضع الاختبار. فتح الزائر عنوان نجاح لا يثبت وقوع دفع.
مثال عملي
للتوضيح، قد يكون المنتج Sample digital workshop بسعر اختبار لمرة واحدة قدره 5 دولارات أمريكية. ينبغي أن يوضح الزر أنه يفتح دفعًا تجريبيًا؛ ولا تعد الصفحة أو هذا الدرس بالتسليم التلقائي للمنتج.
استخدم الصفحة العامة المرفقة لتمرين Payment Link مستضاف أساسي. ساعدني في إنشاء منتج وسعر تجريبيين في بيئة Stripe التجريبية الخاصة بي، ووضع رابط الدفع التجريبي العام فقط في إعداد الصفحة. لا تضبط مسار قاعدة البيانات أو webhook الاختياري، ولا تستخدم بيانات تشغيل فعلي. ساعدني في نشر صفحة التدريب المقصودة وحدها والتحقق من دفعة تجريبية في لوحة المزود. صفحة العودة ليست دليل دفع.Stripe: إنشاء Payment Link · Stripe: الاختبار
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
اقبل دفعة اختبار عبر صفحة دفع مستضافة
ابدأ بصفحة اختبار يستضيفها المزوّد وحد نجاح واضح التعريف.
يتيح Payment Link مستضاف للمزوّد جمع تفاصيل الدفع دون وضع حقول بطاقة في صفحتك. لا يستخدم هذا التدريب إلا بيئة Stripe التجريبية وقيم بطاقات الاختبار.
يفتح الموقع صفحة الدفع، بينما يتلقى الخادم أحداث دفع موقعة ويسجّل إيصالًا. صفحة العودة تنقل فقط: يستطيع أي شخص فتح رابط، لذا لا يثبت وجودها الدفع.
مثال محلول
يجب ألا ينشئ فتح success.html مباشرة إيصالًا. يمكن لجلسة مدفوعة متحقق منها من Payment Link الاختباري المعدّ إنشاء إيصال حتى إن لم يعد العميل إلى موقعك.
Stripe: بعد الدفع عبر Payment Link · Stripe: الاختبار
Extra implementation exercise
يزور مستخدم /success.html?paid=true. هل ينبغي أن يمنحه نظامك منتجًا مدفوعًا؟
عرض حل نموذجي مشروح
لا. يتحكم الزائر بمعامل الاستعلام. استخدم حدث مزوّد متحققًا منه أو فحص مزوّد في الخادم مرتبطًا بالمعاملة المقصودة.
- ترفض الروابط التي يتحكم بها مقدم الطلب دليلًا على الدفع.
- تشترط حالة دفع متحققًا منها لدى المزوّد.
خطأ شائع
إتاحة مشتريات لأن صفحة نجاح فُتحت.
الخطوة 2
أنشئ رابط الاختبار واربطه
استخدم لوحة المزود ودع المساعد يعدّل الصفحة.
أنشئ المنتج والسعر التجريبيين للدفع مرة واحدة وPayment Link في حسابك. افتح صفحة الدفع العامة دون دخول، ثم أعطِ رابط الاختبار للمساعد ليربطه بالصفحة العامة المرفقة.
افحص العنصر والمبلغ والعملة وبيئة الاختبار قبل المتابعة. رابط الدفع التجريبي العام وحده هو ما يوضع في هذه الصفحة؛ لا يحتاج الرابط الأساسي إلى مفتاح توقيع أو API خاص.
مثال عملي
يفتح الإعداد الناجح صفحة الدفع التجريبية العامة للمنتج دون تسجيل دخول. صفحة إعدادات حساب Stripe أو القيمة المؤقتة test_REPLACE دون تغيير ليست رابط دفع قابلًا للاستخدام.
جرّب بنفسك
هل يفتح زر الموقع صفحة الدفع التجريبية المقصودة بالعنصر والسعر الصحيحين؟
عرض حل نموذجي مشروح
مثال فحص: يفتح رابط الموقع دفعًا تجريبيًا عامًا لمنتج Sample digital workshop بسعر USD 5 دون طلب دخول حسابي في Stripe. الرابط التجريبي العام وحده مُعدّ في الصفحة؛ ولا يلزم مفتاح API أو سر webhook لهذا المسار الأساسي.
- يقارن الدفع المستضاف دون دخول بالمنتج والمبلغ والعملة ووضع الاختبار المقصودين.
- يضع رابط Payment Link التجريبي العام وحده في إعداد الصفحة المرفقة.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
اضبط صفحة الدفع الاختبارية المنفصلة
افصل روابط الدفع العامة عن بيانات اعتماد الخادم وأسرار 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؛ نسخ السر الخاطئ يسبب فشل توقيع.
Extra implementation exercise
أيهما مكانه public/config.js: رابط الدفع الاختباري أم سر توقيع whsec؟
عرض حل نموذجي مشروح
رابط الدفع العام فقط مكانه هناك. أبقِ سر webhook ومفاتيح المزوّد وقاعدة البيانات السرية في متغيرات بيئة الخادم.
- تُبقي أسرار التوقيع وAPI في الخادم.
- تستخدم وجهة الدفع العامة فقط في شيفرة المتصفح.
خطأ شائع
الخلط بين سر نقطة إعادة التوجيه المحلية وسر نقطة النهاية المستضافة.
الخطوة 3
أكمل دفعة تجريبية واحدة لدى المزود
استخدم تعليمات الاختبار الرسمية وافحص نتيجة الحساب.
اتبع دليل اختبار Stripe المرتبط داخل بيئة الاختبار فقط. أكمل عملية دفع تجريبية، ثم اعثر على دفعتها أو جلستها الفعلية في حسابك.
تحقق هناك من المبلغ والعملة المتوقعين ومن أن الحالة تؤكد السداد (paid). قد يختلف اكتمال مسار الصفحات عن الحالة النهائية للدفع، خصوصًا لطرق تُسوّى لاحقًا.
مثال عملي
«انتهت خطوات الدفع» و«تأكد سداد الدفعة» ليستا دائمًا الملاحظة نفسها.
جرّب بنفسك
ماذا أفاد سجل المزود فعلًا بشأن دفعتك التجريبية؟
عرض حل نموذجي مشروح
مثال نتيجة مزود: الدفعة التجريبية المطابقة مسددة بمبلغ USD 5، وهو السعر التجريبي المختار. إذا عرض المزود بدلًا من ذلك أنها قيد المعالجة أو غير مسددة، فسأسجل تلك الحالة، لا أعد الطلب مدفوعًا لأن صفحة الدفع انتهت.
- يعثر على الدفعة التجريبية المطابقة وحالة سدادها الفعلية في حساب المزود.
- يقارن المبلغ والعملة المسجلين بسعر الاختبار المختار.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
تحقق من الحدث وسجّل حالة الدفع مرة واحدة
صادِق الحمولة الخام قبل تفسير 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 وإعادة المحاولات
Extra implementation exercise
لماذا لا يمكن اعتبار checkout.session.completed مع payment_status=unpaid طلبًا مدفوعًا بعد؟
عرض حل نموذجي مشروح
تؤكد بعض طرق الدفع لاحقًا. انتظر حالة مدفوعة متحققًا منها، بما في ذلك حدث النجاح غير المتزامن حيث ينطبق، قبل تسجيل إيصال مدفوع.
- تفصل اكتمال صفحة الدفع عن حالة دفع مسوّاة.
- تنتظر التأكيد المناسب للدفع.
خطأ شائع
تعليم كل صفحة دفع مكتملة على أنها مدفوعة بصرف النظر عن payment_status.
الخطوة 4
جرّب الإلغاء وفتح صفحة العودة مباشرة
تحقق أن الزائر لا يستطيع اصطناع نتيجة دفع بالتنقل بين الصفحات.
ابدأ دفعًا تجريبيًا منفصلًا واتركه دون إكمال السداد، أو استخدم مسار إلغاء توفره الصفحة المستضافة فعلًا. وافتح بصورة منفصلة صفحة success.html المرفقة مباشرةً. قارن الحالتين بسجلات الدفع التجريبية لدى المزود.
قد يبقى الدفع المتروك غير مكتمل أو مفتوحًا بدل أن يحمل حرفيًا حالة canceled. ولا ينبغي الإبلاغ عن أي من الإجراءين كشراء جديد مسدد. الصفحة الأساسية لا تسلّم المنتج تلقائيًا.
مثال عملي
فتح success.html أو إضافة paid=true إلى رابطها لا ينشئ دفعة مسددة مطابقة في Stripe. العودة إلى الموقع وإثبات الدفع عمليتان منفصلتان.
جرّب بنفسك
ماذا أثبت الإلغاء وفتح صفحة العودة مباشرة؟ وما الذي لم يثبتاه؟
عرض حل نموذجي مشروح
في هذا الفحص التوضيحي، تُرك الدفع الثاني غير مكتمل ولم تنشأ دفعة مسددة جديدة. عرض فتح success.html مباشرة رسالة العودة فقط. لا يثبت أي إجراء عملية شراء، ولا تمنح الصفحة الأساسية وصولًا تلقائيًا إلى المنتج.
- يميز الدفع الملغى أو غير المكتمل عن دفعة مطابقة مسددة.
- يدرك أن فتح صفحة العودة مباشرةً لا يثبت الدفع أو يمنح التسليم.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
تتبّع دفعة اختبار واحدة من البداية للنهاية
طابق جلسة الدفع والحدث الموقع والإيصال المخزن.
استخدم قيم بطاقات الاختبار الرسمية فقط في صفحة الدفع التجريبية. اعثر على الجلسة الناتجة وتسليم webhook في حسابك، ثم افحص جدول payment_receipts الخاص في مشروع التدريب.
تحقق من المبلغ والعملة مقابل تلك الجلسة. أعد إرسال الحدث المشروع نفسه وأكد بقاء صف واحد. جرّب طلبًا غير موقع وزيارة مباشرة لصفحة النجاح؛ يجب ألا ينشئ أي منهما سجل دفع.
مثال محلول
تثبت استجابة webhook بالحالة 200 أن المعالج أقر شيئًا. افحص الإيصال والجلسة المطابقين بدل افتراض أن كل الأحداث تخص المنتج المقصود.
Extra implementation exercise
يعيد webhook الحالة 200 لحدث غير مرتبط. هل يعني ذلك وجوب وجود إيصال؟
عرض حل نموذجي مشروح
لا. يقر المعالج الأحداث المتجاهلة دون إيصال. يجب ألا تنشئ السجل المقصود إلا جلسة اختبار مدفوعة مطابقة.
- تفهم الأحداث المتجاهَلة عمدًا.
- تطابق الحالة المخزنة بالجلسة المدفوعة المحددة.
خطأ شائع
توقع أن يمثل كل webhook مُقرّ طلب شراء جديدًا.
الخطوة 5
سلّم مسار الدفع الأساسي
أكمل رابطًا مفيدًا دون الادعاء بوجود نظام تجارة متكامل.
كرّر فحص زر الموقع والدفع التجريبي بعد أي إصلاح. احفظ صفحة التدريب ورابطها وسجلًا للمحاولات الناجحة والملغاة أو غير المكتملة، بعد إزالة المعلومات الحساسة.
قبل المبيعات الحقيقية، تحقق من أهلية نشاطك وحسابك والسعر والعملة والشروط وطريقة التشغيل. الوصول التلقائي والأحداث الموقّعة واستعادة قاعدة البيانات ضمن المادة المتقدمة الاختيارية أدناه.
مثال عملي
زر دفع مستضاف يعمل نتيجة صغيرة صالحة؛ لكنه لا يثبت وجود نظام خلفي لتسليم المنتج لم يُبنَ بعد.
جرّب بنفسك
مواد البداية
ملفات البداية ومحتوى الاختبار مرفقة. التحقق الفعلي يتطلب حسابك أو بريدك أو نطاقك وفق المتطلبات السابقة. الفحص المحلي ممكن؛ سجّل الخطوات الحية التي لم تنفّذها على أنها غير مختبرة.
قدّم مسار الاختبار والنتائج الفعلية في البيئة التجريبية وما يلزم قبل إطلاق حقيقي.
ما المطلوب إنجازه رابط أو صفحة الدفع التجريبي والملاحظات الفعلية للدفع والإلغاء في البيئة التجريبية، دون تحصيل حقيقي.
عرض حل نموذجي مشروح
مثال تسليم: تفتح الصفحة الدفع التجريبي للورشة بسعر USD 5؛ وتوجد دفعة تجريبية مطابقة مسددة بقيمة USD 5؛ والمحاولة المتروكة غير مدفوعة؛ وفتح صفحة العودة مباشرةً لا يغير أي سجل. لم يُختبر خصم حقيقي أو تسليم منتج تلقائي. قبل الإطلاق الفعلي، ما زلت بحاجة إلى حساب مؤهل وشروط حقيقية وعملية تسليم متحقق منها.
- يقدم المسار التجريبي العام المُعدّ ونتائج السداد وعدم الإكمال أو الإلغاء.
- يوضح أن الخصم الحقيقي والتسليم التلقائي خارج الاختبار الأساسي المكتمل.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
مهمتك: تدرّب على التعافي دون رسوم حقيقية
يجب أن يتعافى مسار الدفع من كتابة قاعدة بيانات فائتة.
في المشروع القابل للاستغناء عنه، استخدم إعداد قاعدة بيانات غير صحيح مؤقتًا وأعد إرسال حدث اختبارك المدفوع المشروع. لاحظ استجابة غير ناجحة وعدم وجود إيصال جديد. استعد الإعداد وأعد الإرسال، ثم تحقق من صف مطابق واحد بالضبط.
اشرح ما يتبقى قبل البيع الحقيقي: إعداد حساب وعمل مدعوم، وسعر وعملة وشروط صحيحة، وتنفيذ دائم للطلبات، وتسوية ومبالغ مستردة ومراقبة تشغيلية. تسجّل هذه الورشة إيصالات اختبار فقط.
مثال محلول
إذا فشل التخزين لكن نقطة النهاية قالت «نجاح»، فقد تتوقف إعادة المحاولات التلقائية قبل وجود سجلك. الفشل الصادق جزء من معالجة دفع موثوقة.
يتوفر الشرح المرجعي الكامل في reference/assignment-walkthrough.txt. قارن خطواته بنتيجتك؛ واملأ سجل الاختبار بملاحظات من مشروعك أنت.
Extra implementation exercise
أظهر محاولة تخزين فاشلة وتعافيًا ناجحًا آمنًا من التكرار.
عرض حل نموذجي مشروح
ثبّت التبعيات في مشروع التدريب المنفصل باستخدام npm install؛ ينشئ ذلك package-lock.json، واحتفظ به مع المشروع. استخدم Payment Link اختباريًا وبيانات اعتماد sk_test_ فقط. الرابط العام ليس سر توقيع webhook.
اعثر على جلسة اختبارك المدفوعة المطابقة وتسليم webhook الموقع وإيصال خاص يطابق session_id والمبلغ والعملة. أعد تسليم الحدث: يجب أن يترك المفتاح الأساسي وتفضيل ignore-duplicates إيصالًا واحدًا. يجب ألا ينشئ طلب غير موقع أو زيارة مباشرة لصفحة النجاح أي إيصال.
للتدرب على الفشل، غيّر SUPABASE_URL مؤقتًا في البيئة المحلية أو الخادم القابلة للاستغناء عنها فقط إلى هدف اختبار غير صحيح. أعد تسليم الحدث المشروع نفسه ولاحظ فشلًا قابلًا لإعادة المحاولة. استعد الإعداد وأعد التسليم وتحقق من إيصال دائم واحد. لا تغيّر إعدادات الإنتاج أو تختبر ببطاقة حقيقية أبدًا.
- لا يقر فشل الحفظ الدائم بنجاح المعالجة.
- ينشئ التعافي إيصالًا واحدًا؛ ولا تُستخدم تفاصيل دفع أو أموال حقيقية.
خطأ شائع
تسمية مسجّل إيصالات نظام تجارة إنتاج كاملًا.
هل أفادك هذا الدرس؟
اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.
واصل التعلّم
- كيف تنشئ أول موقع شخصي لك
- كيف تنشر موقعك من GitHub
- كيف تربط نطاقًا مخصصًا بموقعك
- كيف تعدّ البريد على نطاقك الخاص
- كيف تجعل موقعك قابلًا للاستخدام على الهواتف
- كيف تجعل صور موقعك تُحمّل أسرع
- كيف تصلك ملاحظات الموقع إلى صندوق بريدك
- كيف تضيف اشتراكات البريد إلى موقعك
- كيف ترسل رسائل بريد آلية من موقعك
- كيف تحفظ إرساليات النماذج في قاعدة بيانات
- كيف تتيح للناس تسجيل الدخول إلى موقعك
- كيف تُبقي صفحة خاصة
- كيف تتيح للمستخدمين تعديل معلومات ملفاتهم الشخصية
- كيف تتيح للمستخدمين رفع الصور
- كيف تُبقي مفاتيح API خارج الواجهة الأمامية
- كيف تعرض بيانات من واجهة API خارجية على موقعك
- كيف تضيف روبوت محادثة بالذكاء الاصطناعي إلى موقعك
- كيف تجعل روبوت محادثة يجيب من محتواك الخاص
- كيف تضيف مدونة إلى موقعك
- كيف تضيف بحثًا إلى موقعك
- كيف تضيف لغة أخرى إلى موقعك
- كيف تساعد Google على العثور على موقعك
- كيف تصلح معاينة موقعك عند مشاركة رابط
- كيف تقيس الزيارات والإجراءات المفيدة على موقعك
- كيف تتيح للزوار حجز موعد
- كيف تعاين تغييرات موقعك قبل النشر
- كيف تتراجع عن نشر موقع معطّل
- كيف تنسخ بيانات موقعك احتياطيًا وتستعيدها
- كيف تجد الأخطاء في موقعك المنشور وتصلحها