ما تحتاجه
| الحقل | ما يفعله |
|---|---|
| Client ID | يعرّف تطبيق PayPal الخاص بك في نداءات الواجهة البرمجية. مقترَن بالسر. |
| Client secret | النصف السري من مصادقة الواجهة البرمجية. مع Client ID، ينشئ الطلب. سري. |
| Webhook ID | يعرّف الـ webhook الذي يوقّعه PayPal، فنتمكن من التحقق من كل تسليم. |
| عنوان النجاح / عنوان الإلغاء | حيث يصل المشتري بعد الدفع أو التراجع. |
لماذا نطلب كل حقل
Client ID
يعرّف تطبيق PayPal الخاص بك في نداءات الواجهة البرمجية. ويعمل فقط حين يُقرَن بـ Client secret.
Client secret
النصف الخاص من مصادقة الواجهة البرمجية. مع Client ID، يتيح لنا إنشاء الطلب، فتجري الدفعة عبر حسابك.
Webhook ID
كيف نؤكّد أن webhook وارداً من PayPal فعلاً: يعرّف PayPal كل webhook بمعرّف، ونستخدمه لنسأل PayPal مباشرة عمّا إذا كانت رسالة معيّنة أصيلة. وذلك يمنع أي شخص من تزوير حدث "مدفوع".
عنوان النجاح والإلغاء
إعدادات بسيطة: حيث يصل المشتري بعد الدفع أو التراجع. ليست سرية.
الإعداد
- افتح لوحة تحكم PayPal Developer
سجّل الدخول على developer.paypal.com. يمنحك PayPal Sandbox مجانياً بحسابات تجارية وهمية وحسابات مشترين وهميين، فتستطيع الاختبار دون تحريك مال حقيقي. يسير هذا الدليل عبر Sandbox؛ تدفق الإنتاج مطابق، فقط قلّب مبدّل Sandbox / Live (أعلى اليسار) واستخدم حساب PayPal for Business. من لوحة التحكم، افتح Apps & Credentials.
PayPal Developer → Apps & Credentials - أنشئ تطبيقاً
في صفحة API Credentials، أكّد تحديد مبدّل Sandbox، ثم انقر Create App (أعلى اليمين).
PayPal → Apps & Credentials → Create App - سمِّه واختر Merchant
أدخل App Name (مثلاً "Coin Moebius")، اترك النوع على Merchant، اختر حساب تجاري sandbox، وانقر Create App.
PayPal → Create App - انسخ Client ID وClient secret
يفتح PayPal تطبيقك الجديد. انسخ Client ID واكشف وانسخ Secret key. (يمكنك أيضاً نسخ كليهما من صف Default Application في قائمة API Credentials.) احتفظ بهما.
1. PayPal → API Credentials → تطبيقك في القائمة 2. PayPal → تطبيقك → Client ID والـ Secret Client secret سري، تعامل معه ككلمة مرور. لتطبيق sandbox والتطبيق الحي كل منهما زوجه الخاص، لا تخلط بينهما.
- أضف webhook
انزل في صفحة التطبيق إلى قسم Sandbox Webhooks وانقر Add Webhook. في حقل Webhook URL، الصق عنوان webhook PayPal الخاص بمشروعك (أدناه). ثم اختر الأحداث التي يستمع إليها Coin Moebius، واحفظ.
- المدفوعات لمرة واحدة: CHECKOUT.ORDER.APPROVED، وPAYMENT.CAPTURE.COMPLETED، وPAYMENT.CAPTURE.DENIED، وPAYMENT.CAPTURE.DECLINED، وPAYMENT.CAPTURE.REFUNDED، وPAYMENT.CAPTURE.REVERSED، وCUSTOMER.DISPUTE.CREATED.
- الاشتراكات (فقط إن كنت تبيعها): BILLING.SUBSCRIPTION.ACTIVATED، وBILLING.SUBSCRIPTION.UPDATED، وBILLING.SUBSCRIPTION.CANCELLED، وBILLING.SUBSCRIPTION.PAYMENT.FAILED، وPAYMENT.SALE.COMPLETED. إن لم تكن تفوتر بصفة دورية، تخطَّ هذه.
- في عجلة؟ تحديد All Events (البدل في الأعلى) يعمل أيضاً، نتجاهل ما لا نستخدمه.
https://api.coinmoebius.com/webhook/paypal/<your project id>PayPal → تطبيقك → Add webhook معرّف مشروعك موجود أسفل اسم المشروع في لوحة تحكم Coin Moebius؛ أدرجه في العنوان أعلاه. تُظهر بطاقة المزود المتصل (الخطوة الأخيرة) العنوان نفسه للمرجع.
- انسخ Webhook ID
يظهر webhook الآن في قائمة Sandbox Webhooks. انسخ Webhook ID المعروض بجانبه. هكذا يطلب Coin Moebius من PayPal تأكيد أن كل webhook أصيل. سجّل webhook منفصلاً في sandbox وفي الإنتاج.
PayPal → تطبيقك → Sandbox Webhooks → Webhook ID - في Coin Moebius: إضافة مزود → PayPal
في مشروعك، افتح تبويب Providers، انقر إضافة مزود، اختر Connect a service، ثم اختر PayPal. اضبط عنوان النجاح وعنوان الإلغاء. تختبر ببيانات اعتماد sandbox؟ استخدم تبويب Test (اختياري) والصق Client ID وClient secret وWebhook ID هناك، ثم انقر حفظ. تنتقل مباشرة إلى الإنتاج؟ استخدم تبويب Live. مجموعة Test كلٌّ أو لا شيء: الحقول الثلاثة، أو لا شيء.
Coin Moebius → إضافة مزود → PayPal - أنت متصل الآن
يظهر PayPal الآن في تبويب Providers الخاص بك مع تاريخ الاتصال (موسوم بـ TEST حين استخدمت بيانات اعتماد sandbox). تُظهر البطاقة عنوان webhook نفسه الذي لصقته في PayPal، بالإضافة إلى تعديل وفصل.
Coin Moebius → Providers → PayPal (متصل) - اختبر بمشترٍ من الـ sandbox
للدفع عبر تسوية اختبارية، تحتاج إلى بيانات تسجيل دخول مشتري sandbox. في PayPal، افتح Testing Tools → Sandbox Accounts لرؤية حسابات Business وPersonal الوهمية.
PayPal → Testing Tools → Sandbox Accounts - احصل على بيانات تسجيل دخول المشتري
افتح حساب Personal (المشتري) لعرض Login Info الخاص به: عنوان sandbox URL والبريد الإلكتروني وكلمة المرور. سجّل الدخول على sandbox.paypal.com بتلك البيانات حين تطلب منك تسوية اختبارية الدفع. لا يتحرك مال حقيقي.
PayPal → حساب Sandbox → Login Info
بعد أن تربط
أجرِ دفعة اختبار واحدة قبل الإطلاق:
- أنشئ منتجاً واضبط بيئته على Testing. يشغّل ذلك المنتج على بيانات اعتماد الـ sandbox الخاصة بك، فيمكنك إجراء طلب كامل دون تحريك مال. (إن تخطّيت مجموعة الـ sandbox، فإن منتج Testing يعود إلى الحي، فأضِفها أولاً.)
- ضع زر الشراء على صفحة (ملف HTML محلي يعمل) موجَّهاً إلى مشروعك.
- أتمِم الدفع بالدفع بحساب مشتري الـ sandbox الخاص بك.
- افتح تبويب المعاملات. يظهر صف جديد، موسوم Testing. وحين تبلغ حالته succeeded، تعمل بيانات اعتمادك والـ webhook من البداية إلى النهاية.
بدّل بيئة المنتج إلى Live حين تكون جاهزاً للمدفوعات الحقيقية.
حل المشكلات
ابدأ بالتحقق. في لوحة التحكم، انقر تحقق (أو تحقق من بيانات اعتماد الاختبار للـ sandbox) لفحص بيانات اعتماد العميل لديك.
يفشل التحقق.
أعِد نسخ Client ID وClient secret. لتطبيق الـ sandbox والتطبيق الحي زوجان مختلفان، فلا تخلط بينهما.
تكتمل الدفعة لكن الطلب يبقى معلّقاً.
يجب أن يأتي Webhook ID من التطبيق والبيئة نفسهما اللذين أتت منهما بيانات اعتماد عميلك. بيانات الاعتماد الحية تحتاج Webhook ID الحي. أكّد أن عنوان الـ webhook يطابق.
أكّده من البداية إلى النهاية.
PayPal Developer Dashboard → Webhooks Simulator: أرسل حدث عينة إلى عنوان webhook الخاص بك، ثم راقب تحديث الطلب.
جيد أن تعرف
تدوير الأسرار. ولّد client secret جديداً في أي وقت، ثم الصقه. تبقى الحقول السرية فارغة عند التعديل.
أسئلة؟ Join our Discord