VibeFox Satispay for PrestaShop — المساعدة

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: الإصدار 8.0 أو أحدث مع امتداد OpenSSL. ترفض الوحدة التثبيت على إصدارات PHP الأقدم أو دون OpenSSL.

العملة: EUR. تقبل Satispay الدفع باليورو فقط، لذلك تُخفى طريقة الدفع عندما لا تكون عملة سلة التسوق EUR.

حساب Satispay: حساب Satispay Business. لا تنسخ أي مفاتيح API: تتصل الوحدة برمز تفعيل لمرة واحدة تُنشئه في Satispay Business Dashboard (انظر قسم الإعدادات). للاختبارات تحتاج إلى حساب sandbox من Satispay، تطلبه من Satispay للمطورين.

المتجر العام: يجب أن يكون متجرك متاحًا من الإنترنت حتى تتمكن Satispay من استدعائه عند تغيّر حالة الدفعة. لا يلزم إعداد أي شيء في Satispay لهذا الغرض.

مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد.

التثبيت

1. في لوحة الإدارة انتقل إلى Modules > Module Manager وانقر Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع انقر Configure، أو ابحث لاحقًا عن VibeFox Satispay Gateway في قائمة الوحدات وانقر Configure.

3. أدخل مفتاح ترخيص VibeFox في الحقل License key ضمن كتلة الترخيص أعلى صفحة Configure، ثم انقر Activate (انظر مفتاح الترخيص).

4. اختر البيئة: فعّل Sandbox Mode للاختبارات، واتركه معطّلًا للدفعات الحقيقية.

5. الصق رمز تفعيل لتلك البيئة في Activation Code وانقر Save. عندها سيعرض الحقل Status الحالة Connected مع Key ID.

6. فعّل Enable/Disable وانقر Save. اختبر دفعة في بيئة الاختبار، ثم عطّل Sandbox Mode واربط البيئة الفعلية برمز تفعيل فعلي.

عند التثبيت تُنشئ الوحدة حالة الطلب Satispay payment on hold. تقدم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها في Payment > Preferences، ويجب السماح للوحدة باليورو هناك.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Satispay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها.

الدفع

ما يراه العملاء في قائمة طرق الدفع.

Enable/Disable: يُفعّل Enable Satispay payment طريقة الدفع أو يعطّلها. الافتراضي: off.

Title: اسم طريقة الدفع المعروض في صفحة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Satispay. مطلوب.

Description: النص المعروض أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

اتصال Satispay

Status: حالة البيئتين، مثلًا Live: Connected مع Key ID أو Sandbox: Not connected، وأي بيئة قيد الاستخدام. طالما لم تكن البيئة المستخدمة متصلة، يعرض الحقل Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode: يستخدم بيئة Satispay التجريبية (sandbox). لا تُحصَّل مبالغ من دفعات sandbox. الافتراضي: off. البيئتان لهما مفاتيح منفصلة: اربط كل بيئة برمز تفعيل خاص بها. وأثناء استخدام sandbox يرى العملاء أسفل طريقة الدفع Sandbox mode: no real money is charged.

Activation Code: لربط البيئة المختارة أعلاه، الصق رمز تفعيل جديدًا من 6 أحرف وانقر Save. تُنشأ الرموز الفعلية في Satispay Business Dashboard ضمن قسم Online shop. وتأتي رموز sandbox مع حساب Satispay التجريبي. يُستخدم الرمز مرة واحدة ولا يُخزَّن. اترك الحقل فارغًا للإبقاء على الاتصال الحالي.

عند الحفظ بالرمز تُنشئ الوحدة زوج مفاتيح RSA، وترسل المفتاح العام والرمز إلى Satispay، وتحفظ Key ID ومفاتيح تلك البيئة في إعدادات المتجر. لا تُعرض المفاتيح الخاصة أبدًا. عند النجاح تعرض الصفحة، مثلًا، Satispay Live connected. Key ID: متبوعًا بالمعرّف. إذا رفضت Satispay الرمز، تعرض الصفحة Satispay activation failed: مع رسالة Satispay، وتطلب منك التحقق من أن الرمز لهذه البيئة وأنه لم يُستخدم بعد. يُرفض الرمز الذي يحتوي على أحرف غير الحروف والأرقام قبل إرسال أي شيء. حفظ رمز جديد لبيئة ما يستبدل اتصالها السابق.

إشعارات الدفع

لا يلزم إعداد شيء في Satispay. لكل دفعة عنوان استدعاء (callback URL) خاص بها، تستدعيه Satispay عند تغيّر الدفعة، وتعيد الوحدة قراءة الدفعة من Satispay API قبل إنشاء الطلب أو تغييره. يعرض الحقل Callback URL مثالًا على هذا العنوان. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}، وقد يسبقه رمز لغة مثل /en/. يجب أن يكون العنوان متاحًا من الإنترنت، دون مصادقة أساسية أمامه. يعمل الاستدعاء حتى عندما يكون المتجر في وضع الصيانة، ولا تحجبه قيود الدول في متجرك.

متقدم

Debug log: يكتب استدعاءات API وأحداث الدفع في logs/satispay_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح وبيانات العملاء. تُسجَّل الأخطاء دائمًا، حتى عندما يكون هذا الخيار معطّلًا. الافتراضي: off.

Log: يعرض حجم السجل وآخر إدخالاته. انقر Clear log لتفريغه.

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات ومفاتيح Satispay للبيئتين والسجل. تبقى دائمًا دفعات Satispay والاستردادات المحفوظة للطلبات، وحالة الطلب Satispay payment on hold. الافتراضي: off.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Satispay) ويؤكد الطلب. تُنشئ الوحدة دفعة Satispay بإجمالي سلة التسوق باليورو، مع رقم السلة كمرجع، وتنقل العميل إلى صفحة دفع Satispay. على الحاسوب يمسح العميل رمز QR بتطبيق Satispay. على الهاتف يؤكد العميل الدفع في التطبيق. لا يوجد طلب بعد في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Satispay: تقرأ الوحدة الدفعة من Satispay API، وتتحقق من أنها أُنشئت لسلة التسوق هذه، وتقارن حالتها ومبلغها (بالسنت) وعملتها بالسلة. يحدث هذا سواء استدعت Satispay عنوان الاستدعاء أو عاد العميل، أيهما يحدث أولًا. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة. إذا لم تؤكد Satispay الدفعة بعد عند عودة العميل، تعرض صفحة Payment confirmation الرسالة Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. وزر Check again. ينشئ الاستدعاء الطلب فور وصوله.

إذا غادر العميل صفحة Satispay دون الدفع، تُلغي الوحدة الدفعة لدى Satispay، فلا يمكن دفع الصفحة المتروكة بعد ذلك. يعود العميل إلى صفحة الدفع مع الرسالة Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. تظهر الرسالة نفسها عندما يرفض العميل الدفع في التطبيق. تبقى سلة التسوق محفوظة.

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

إذا تعذّر بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة: Satispay is not available at the moment. Please choose another payment method. عندما لا يكون المتجر متصلًا أو ترفض Satispay المفاتيح، أو Unable to create the Satispay payment. Please try again or choose another payment method. للأخطاء الأخرى. يُكتب السبب في السجل.

تقبل الوحدة الدفعات الفردية باليورو فقط. لا تدعم الاشتراكات أو وسائل الدفع المحفوظة أو التفويضات المسبقة أو قسائم الطعام. لا يوجد فحص مجدول للدفعات المعلّقة: إذا لم يصل استدعاء Satispay ولا عودة العميل إلى متجرك، فلن يُنشأ أي طلب، وستظل الدفعة مرئية في Satispay Dashboard.

الطلبات والاسترداد

حالات الطلب

No order yet: أُرسل العميل إلى Satispay ولم يدفع، أو لم تؤكد Satispay الدفعة بعد. لا توجد إلا سلة التسوق ودفعة Satispay الخاصة بالوحدة.

Payment accepted: تم تأكيد الدفعة. تُسجَّل الدفعة بمعرّف دفعة Satispay كمعرّف للمعاملة، وتعرض ملاحظة دفعة Satispay والمبلغ وطريقة التحقق (callback، redirect أو checkout).

Satispay payment on hold: أبلغت Satispay عن مبلغ أو عملة يختلفان عن إجمالي سلة التسوق (مثلًا، تغيّرت السلة في تبويب آخر بعد بدء الدفع)، أو قُبلت الدفعة بعد إلغاء الطلب. يُسجَّل المبلغ المستلم على الطلب، وتشرح الملاحظة ذلك. تحقّق من الدفعة في Satispay Dashboard، ثم نفّذ الطلب أو استرد الدفعة. إذا قُبلت لاحقًا دفعة أخرى للسلة نفسها بالمبلغ الصحيح، ينتقل الطلب إلى Payment accepted.

Refunded: استُرد المبلغ كاملًا عبر الوحدة.

إذا قُبلت دفعة ثانية لطلب مدفوع بالفعل، فلن يتغير الطلب. تطلب منك ملاحظة استرداد الدفعة المكررة من Satispay Dashboard. ولن يُعاد فتح طلب ملغى أو مسترد بسبب تأكيد متكرر.

كتلة دفع Satispay

تعرض صفحة الطلب كتلة Satispay payment تتضمن معرّف دفعة Satispay وحالتها والمبلغ المدفوع والمسترد، وشارة Sandbox لدفعات sandbox، وسجل الاسترداد، وقائمة Satispay payments of this cart بكل محاولة دفع وبيئتها، وSatispay notes الخاصة بالطلب.

الاسترداد

في كتلة Satispay payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واكتب سببًا إذا أردت، ثم انقر Refund via Satispay. أكّد السؤال Refund this amount through Satispay? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات Modules. الاستردادات محدودة بالمبلغ الذي حصّلته Satispay للدفعة، لذلك بعد اختلاف في المبلغ يمكنك الاسترداد حتى ما دفعه العميل فعلًا، لا إجمالي الطلب. يُرسل الاسترداد إلى البيئة التي تمّت فيها الدفعة (الفعلية أو sandbox)، لذا يجب أن تبقى تلك البيئة متصلة. لا يُعتبر الاسترداد منجزًا إلا إذا قبلته Satispay: يُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع معرّف استرداد Satispay والسبب. إذا لم تقبل Satispay الاسترداد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. يضع الاسترداد الكامل الطلب في حالة Refunded. الاسترداد الجزئي لا يغيّر الحالة.

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا ترسل المال عبر Satispay. الاستردادات التي تُجرى في Satispay Dashboard لا تُسجَّل في PrestaShop. حدّث الطلب يدويًا عند الحاجة.

مفتاح الترخيص

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Satispay Gateway هي أول كتلة في Modules > Module Manager > VibeFox Satispay Gateway > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، وأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: presta-payment-satispay ورابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure لهذه الوحدة. وتتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

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

بدون مفتاح نشط لا يظهر Satispay للعملاء في صفحة الدفع. إذا بدأ دفع على أي حال، يرى العميل الرسالة This payment method is not available. Please choose another one. لا تعرف واجهة PrestaShop الأمامية أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager ضمن تبويب Alerts. الطلبات الحالية لا تتأثر: الدفعات التي بدأت بالفعل ما زالت تُؤكَّد، وتعمل الاستردادات.

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

استكشاف الأخطاء وإصلاحها

لا يظهر Satispay في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة المستخدمة متصلة (يعرض الحقل Status الحالة Connected لها)، وأن عملة السلة EUR. في Payment > Preferences تحقّق من أن الوحدة مسموح بها لليورو ولدولة العميل ولمجموعة العميل.

تمّت الدفعة لكن لم يُنشأ أي طلب: يُنشأ الطلب عندما تستدعي Satispay متجرك أو عندما يعود العميل. تحقّق من أن متجرك متاح من الإنترنت، ودون مصادقة أساسية أمام عنوان الاستدعاء، وفعّل Debug log لرؤية الاستدعاءات في الحقل Log. الدفعة مرئية في Satispay Dashboard.

يرد الاستدعاء بالرسالة Payment status unavailable, retry later. أو Not configured.: تعذّر على الوحدة قراءة الدفعة من Satispay، أو أن بيئة الدفعة غير متصلة. لا يتغيّر أي طلب. ستعيد Satispay الاستدعاء. تحقّق من حالة الاتصال والسجل.

يرد الاستدعاء بالرسالة Busy, retry later.: كانت سلة التسوق تُؤكَّد بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد Satispay الاستدعاء. يعرض السجل السبب.

يرد الاستدعاء بالرسالة Unknown payment. أو Missing or invalid payment_id.: لم تُنشئ هذه الدفعة هذا المتجر لهذه السلة، أو أن الطلب ليس استدعاء Satispay. لا يتغيّر شيء.

يفشل التفعيل: رموز التفعيل تُستخدم مرة واحدة. تحقّق من أن الرمز يخص البيئة المختارة في Sandbox Mode (رمز فعلي للبيئة الفعلية، ورمز sandbox لبيئة sandbox)، وأنشئ رمزًا جديدًا واحفظ من جديد. إذا أفادت الصفحة بتعذّر إنشاء زوج مفاتيح RSA، فاطلب من مزوّد الاستضافة تفعيل امتداد OpenSSL في PHP. إذا تعذّر الوصول إلى Satispay، فتحقّق من أن خادمك يستطيع فتح اتصالات HTTPS صادرة.

اختفى Satispay من صفحة الدفع بعد الانتقال من sandbox إلى البيئة الفعلية: تستخدم sandbox والبيئة الفعلية مفاتيح مختلفة. الصق رمز تفعيل فعليًا مع تعطيل Sandbox Mode ثم احفظ.

يرى العميل الرسالة This payment method is not available.: طريقة الدفع غير مسموح بها للسلة (الدولة أو العملة أو مجموعة العملاء في Payment > Preferences)، أو أنها معطّلة، أو أن البيئة المستخدمة غير متصلة.

الطلب في حالة Satispay payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Satispay payment (انظر حالات الطلب)، وتحقّق من الدفعة في Satispay Dashboard، ثم نفّذ الطلب أو استرد الدفعة.

يفشل الاسترداد لأن البيئة لم تعد متصلة: تمّت الدفعة في البيئة الفعلية أو في sandbox، ولم تعد لتلك البيئة مفاتيح. أعد ربطها برمز تفعيل، أو استرد الدفعة من Satispay Dashboard.

يفشل الاسترداد برسالة Satispay did not accept the refund: أعادت Satispay حالة غير accepted. لم تُسجّل PrestaShop الاسترداد، وتوضح ملاحظة ذلك. تحقّق منه في Satispay Dashboard.

إلغاء التثبيت

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Satispay Gateway واختر Uninstall. مفتاح الترخيص وحالة الترخيص لهذه الوحدة يُزالان دائمًا. إذا كان Delete data on uninstall مفعّلًا تُحذف الإعدادات ومفاتيح Satispay للبيئتين والسجل. وإذا كان معطّلًا، تُحفظ جميع الإعدادات والمفاتيح لإعادة التثبيت لاحقًا. تبقى دائمًا دفعات Satispay والاستردادات المحفوظة للطلبات، وحالة الطلب Satispay payment on hold، لذا يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت متى أُعيد ربط البيئة. تحتفظ الطلبات الموجودة بملاحظات الدفع ومعرّفات المعاملات.

Satispay علامة تجارية تعود لمالكها. هذه الوحدة غير مرتبطة بـ Satispay ولا معتمدة من قبلها.