ما تحتاجه
| الحقل | ما يفعله |
|---|---|
| Access token | يتيح لنا استدعاء Square لإنشاء رابط الدفع. سري. |
| Webhook signature key | يؤكّد أن webhook أتى فعلاً من Square. سري. |
| Location ID | موقع Square الذي يستلم الدفعة. يحدّد العملة. |
| عنوان النجاح / عنوان الإلغاء | حيث يصل المشتري بعد الدفع أو التراجع. |
لماذا نطلب كل حقل
Access token
يفوّض إنشاء رابط الدفع، فتجري الخصمة عبر حسابك.
Webhook signature key
يثبت أن webhook وارداً من Square فعلاً، فلا يستطيع أحد تزوير حدث "مدفوع". وهو قيمة منفصلة عن access token.
Location ID
يخبر Square أي موقع يستلم المال، ويحدّد عملة الدفع. ليس سرياً.
عنوان النجاح والإلغاء
إعدادات بسيطة: حيث يصل المشتري بعد الدفع أو التراجع. ليست سرية.
الإعداد
- افتح لوحة تحكم Square Developer
سجّل الدخول على developer.squareup.com. لكل تطبيق بيانات اعتماده الخاصة، ويُنشَأ Sandbox مجاني جنباً إلى جنب معه للاختبار. يسير هذا الدليل عبر Sandbox؛ تدفق الإنتاج مطابق، فقط قلّب مبدّل Sandbox / Production واستخدم بيانات اعتماد الإنتاج. لإنشاء تطبيق جديد، انقر مربّع + في شاشة Applications.
Square Developer → Applications - سمِّ تطبيقك
أعطِ التطبيق اسماً ستتعرف عليه (مثلاً "Coin Moebius")، ثم انقر Next.
Square → Name your application - انسخ access token الخاص بك
افتح التطبيق واذهب إلى Credentials. أكّد أن مبدّل Sandbox / Production في الأعلى يطابق البيئة التي تعدّها. انقر أيقونة النسخ بجانب Access token واحتفظ به.
Square → Credentials Access token سري، تعامل معه ككلمة مرور. لـ Sandbox والإنتاج رموز منفصلة، لا تخلط بينها.
- انسخ Location ID الخاص بك
في القائمة اليسرى، افتح Locations. انسخ Location ID للموقع الذي ينبغي أن يستلم المدفوعات. يضبط عملة الدفع، فاختر الموقع الذي تريد تحصيل مدفوعاته بعملته.
Square → Locations - افتح Webhooks → Subscriptions
يسمّي Square نقطة نهاية webhook "اشتراكاً". في القائمة اليسرى، وسّع Webhooks، افتح Subscriptions، وانقر Add subscription.
Square → Webhooks → Subscriptions → Add subscription - أضف الاشتراك واختر الأحداث
أعطِه اسماً (مثل "coin-moebius"). في Notification URL، الصق عنوان webhook Square الخاص بمشروعك (أدناه). ثم، تحت Events، ابحث وأشّر على الأحداث التي يستمع إليها Coin Moebius، ثم انقر حفظ.
- المدفوعات لمرة واحدة: payment.created، وpayment.updated، وrefund.created، وrefund.updated، وdispute.created، وdispute.state.updated.
- الاشتراكات (فقط إن كنت تبيعها): subscription.created، وsubscription.updated، وsubscription.canceled، وsubscription.deactivated، وinvoice.payment_made، وinvoice.scheduled_charge_failed. إن لم تكن تفوتر بصفة دورية، تخطَّ هذه.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription معرّف مشروعك موجود أسفل اسم المشروع في لوحة تحكم Coin Moebius؛ أدرجه في العنوان أعلاه. الأحداث الإضافية غير ضارة، نتجاهل ما لا نستخدمه. تُظهر بطاقة المزود المتصل (الخطوة الأخيرة) العنوان نفسه للمرجع.
- افتح الاشتراك الذي أنشأته للتو
يحفظ Square الاشتراك ويدرجه تحت Webhooks بحالة Enabled. انقر على اسمه لفتح لوحة التفاصيل حيث توجد مفتاح التوقيع.
Square → Webhooks → اشتراكك (مُفعَّل) - انسخ Signature key
في لوحة Properties للاشتراك، انقر أيقونة النسخ بجانب Signature key. هذه هي القيمة التي يستخدمها Coin Moebius لتأكيد أن كل webhook أتى فعلاً من Square. لا توجد إلا بعد إنشاء الاشتراك، ولهذا جاء webhook قبل خطوة الاتصال.
Square → اشتراكك → Signature key - في Coin Moebius: إضافة مزود → Square
في مشروعك، افتح تبويب Providers، انقر إضافة مزود، اختر Connect a service، ثم اختر Square. اضبط عنوان النجاح وعنوان الإلغاء. في تبويب Live، الصق Access token وWebhook signature key وLocation ID، ثم انقر حفظ. تريد الإعداد ببيانات اعتماد sandbox أولاً؟ الصقها في تبويب Test بدلاً من ذلك، ثم أضف بيانات اعتماد الإنتاج لاحقاً من تعديل.
Coin Moebius → إضافة مزود → Square - أنت متصل الآن
يظهر Square الآن في تبويب Providers الخاص بك مع تاريخ الاتصال. تُظهر البطاقة عنوان webhook نفسه الذي لصقته في Square، بالإضافة إلى تعديل وفصل. استخدم مبدّل وضع الاختبار لتشغيل طلب sandbox من البداية إلى النهاية قبل الإطلاق.
Coin Moebius → Providers → Square (متصل) بطاقات Sandbox لا تخصم من بطاقة حقيقية. استخدم البطاقة 4111 1111 1111 1111، وCVV 111، وأي تاريخ انتهاء مستقبلي، وأي رمز بريدي صالح (مثلاً 94103).
بعد أن تربط
أجرِ دفعة اختبار واحدة قبل الإطلاق:
- أنشئ منتجاً واضبط بيئته على Testing. يشغّل ذلك المنتج على بيانات اعتماد الـ sandbox الخاصة بك، فيمكنك إجراء طلب كامل دون تحريك مال. (إن تخطّيت مجموعة الـ sandbox، فإن منتج Testing يعود إلى الحي، فأضِفها أولاً.)
- ضع زر الشراء على صفحة (ملف HTML محلي يعمل) موجَّهاً إلى مشروعك.
- أتمِم الدفع ببطاقة اختبار sandbox من أعلاه.
- افتح تبويب المعاملات. يظهر صف جديد، موسوم Testing. وحين تبلغ حالته succeeded، تعمل بيانات اعتمادك والـ webhook من البداية إلى النهاية.
بدّل بيئة المنتج إلى Live حين تكون جاهزاً للمدفوعات الحقيقية.
حل المشكلات
ابدأ بالتحقق. في لوحة التحكم، انقر تحقق (أو تحقق من بيانات اعتماد الاختبار) لفحص access token والموقع.
يفشل التحقق.
أعِد نسخ access token وLocation ID. لـ Production وSandbox رموز منفصلة، فلا تخلط بينها.
يفشل التحقق من التوقيع، أو يبقى الطلب معلّقاً.
يوقّع Square على عنوان الإشعار الدقيق إضافة إلى الجسد. ويجب أن يطابق العنوان الذي تسجّله في Square عنوان webhook الخاص بك حرفاً بحرف، بلا شُرطة مائلة لاحقة وبلا سلسلة استعلام إضافية. ثم أعِد نسخ signature key من نقطة النهاية نفسها.
أكّده من البداية إلى النهاية.
Square Developer Console → Webhooks → اشتراكك → Send Test Event، ثم راقب تحديث الطلب.
جيد أن تعرف
العملة تتبع الموقع. يخصم الدفع بعملة الموقع الذي تقدّم معرّفه.
تدوير الأسرار. دوّر access token أو signature key في أي وقت، ثم الصق القيمة الجديدة. تبقى الحقول السرية فارغة عند التعديل.
أسئلة؟ Join our Discord