درس مصغّر · العربية

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

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

ابدأ الدرس التفاعلياقرأ ملاحظات الدرس

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

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

قبل أن تبدأ

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

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

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

ما الذي ستتعلمه؟

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

ملفات ورشة العمل

الخطوة 1

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

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

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

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

مثال عملي

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

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

Stripe: إنشاء Payment Link · Stripe: الاختبار

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

Start hereملفات ورشة العمل

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 دون تغيير ليست رابط دفع قابلًا للاستخدام.

Stripe: إنشاء Payment Link

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

Start hereملفات ورشة العمل

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.

اتبع 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: حالة دعم الإصدارات

Extra implementation exercise

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

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

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

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

الخطوة 3

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

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

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

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

مثال عملي

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

Stripe: الاختبار

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

Start hereملفات ورشة العمل

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 طلبًا مدفوعًا بعد؟

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

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

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

    الخطوة 4

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

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

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

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

    مثال عملي

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

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

    Start hereملفات ورشة العمل

    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 لحدث غير مرتبط. هل يعني ذلك وجوب وجود إيصال؟

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

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

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

      الخطوة 5

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

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

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

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

      مثال عملي

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

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

      Start hereملفات ورشة العمل

      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 مؤقتًا في البيئة المحلية أو الخادم القابلة للاستغناء عنها فقط إلى هدف اختبار غير صحيح. أعد تسليم الحدث المشروع نفسه ولاحظ فشلًا قابلًا لإعادة المحاولة. استعد الإعداد وأعد التسليم وتحقق من إيصال دائم واحد. لا تغيّر إعدادات الإنتاج أو تختبر ببطاقة حقيقية أبدًا.

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

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

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

      واصل التعلّم

      استكشف الدروس الأخرى