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

المتطلبات

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

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

وصول المتجر إلى الإنترنت: ترسل MakeCommerce إشعارات الدفع إلى متجرك، لذلك يجب أن يكون الموقع متاحًا عبر الإنترنت. قد يحظر جدار الحماية أو المصادقة الأساسية هذه الإشعارات. ولا يحظرها وضع الصيانة ولا قيود الدول الخاصة بمتجرك.

حساب MakeCommerce: تحتاج إلى Shop ID وSecret key من Merchant Portal الخاص بـ MakeCommerce (Settings > API). ولبيئتي الاختبار والتشغيل المباشر حسابان ومفتاحان منفصلان. ويحدد عقدك مع MakeCommerce طرق الدفع والعملات المتاحة. ولا تُعرض العملات ذات ثلاث خانات عشرية، مثل KWD أو BHD.

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

التثبيت

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

2. عند اكتمال الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox MakeCommerce Payment في قائمة الوحدات وانقر على Configure.

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

4. أدخل Shop ID وSecret key لبيئة الاختبار، وللمدفوعات الفعلية أدخل مفاتيح بيئة التشغيل المباشر (انظر الإعدادات). لا حاجة لأي إعداد في Merchant Portal.

5. فعّل Enable/Disable وانقر على Save. اختبر عملية دفع مع تفعيل Test mode، ثم عطّله لقبول المدفوعات الفعلية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox MakeCommerce Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول، تعرض الصفحة Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. طالما كان وضع الاختبار مفعّلًا. كما تحذّرك عندما تكون طريقة الدفع مفعّلة بينما Shop ID أو Secret key للبيئة الحالية فارغ، وعندما لا تستطيع MakeCommerce تحصيل العملة الافتراضية للمتجر. وفي الحالتين تُخفى طريقة الدفع في إتمام الطلب. وعند الحفظ تُزال المسافات من المفاتيح.

MakeCommerce

Enable/Disable: Enable MakeCommerce payments يفعّل طريقة الدفع أو يعطّلها. الافتراضي: معطّل.

Title: اسم طريقة الدفع الذي يراه العملاء في إتمام الطلب، وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Bank link or card (MakeCommerce). حقل مطلوب.

Description: النص الذي يظهر أسفل طريقة الدفع في إتمام الطلب. الافتراضي: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

حساب MakeCommerce

يوجد Shop ID وSecret key في Merchant Portal الخاص بـ MakeCommerce ضمن Settings > API. لبوابة الاختبار وبوابة التشغيل المباشر حسابان ومفتاحان منفصلان. ويتضمن القسم روابط إلى البوابتين وإلى صفحة التسجيل في MakeCommerce.

Test mode: يستخدم بيئة الاختبار الخاصة بـ MakeCommerce (لا يُخصم أي مبلغ حقيقي). تُنشأ المدفوعات الجديدة في البيئة المختارة باستخدام مفاتيحها. ويتذكر كل طلب البيئة التي تم الدفع فيها: وتتوجه عمليات التحقق من الحالة والاستردادات دائمًا إليها. وعند تفعيله، يرى العملاء أسفل طريقة الدفع العبارة TEST MODE — MakeCommerce test environment, no real money is charged. الافتراضي: مفعّل.

Test Shop ID: Shop ID لحساب الاختبار الخاص بك، بالصيغة xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key: Secret key لحساب الاختبار الخاص بك.

Live Shop ID: Shop ID لحساب التشغيل المباشر الخاص بك.

Live Secret key: Secret key لحساب التشغيل المباشر الخاص بك.

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved secret keys: ضع علامة على مفتاح وانقر على Save لحذفه. ويُبقي الحقل الفارغ القيمة المحفوظة.

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

لا حاجة لأي إعداد في Merchant Portal. يعرض Callback URLs، للاطلاع فقط، عنوان عودة العميل أو إلغائه وعنوان إشعارات الدفع. تحمل كل معاملة عناوين URL الخاصة بها للعودة والإلغاء والإشعار، وهي مبنية على هذه العناوين مع رقم السلة ومفتاح يُضاف إليها. ترسل MakeCommerce رسالة موقَّعة إلى عنوان الإشعار (من الخادم إلى الخادم)، وترسلها عبر متصفح العميل إلى عنوان العودة أو الإلغاء. ويُتحقق من التوقيع باستخدام Secret key للبيئة التي أُنشئت فيها المعاملة. وتُرفض الرسائل التي لا تحمل توقيعًا صالحًا.

تتعامل الوحدة مع حالات المعاملات التالية في MakeCommerce:

يُؤكَّد الدفع أيضًا عندما يعود العميل إلى المتجر. وإذا عاد العميل دون رسالة موقَّعة، تطلب الوحدة الحالة من واجهة برمجة تطبيقات MakeCommerce.

متقدم

Debug log: يسجّل استدعاءات واجهة البرمجة وإشعارات الدفع في logs/wc_mkc_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل المفاتيح أو بيانات العملاء أبدًا. الافتراضي: معطّل.

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

Delete data: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها والسجل. تبقى الطلبات وبيانات دفع MakeCommerce الخاصة بها محفوظة دائمًا. الافتراضي: معطّل.

إتمام الطلب

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا Bank link or card (MakeCommerce)) ويؤكد. تنشئ الوحدة معاملة MakeCommerce بإجمالي السلة وبعملة السلة، وتوجّه العميل إلى صفحة دفع MakeCommerce. هناك يختار العميل رابطًا مصرفيًا أو بطاقة. ويُمرَّر البريد الإلكتروني للعميل وبلده إلى MakeCommerce، وتُفتح الصفحة بلغة المتجر حيثما تدعم MakeCommerce ذلك (الإستونية، والإنجليزية، واللاتفية، والليتوانية، والفنلندية، والروسية، والألمانية، والبولندية)، وإلا فبالإنجليزية. ولا يوجد طلب في هذه المرحلة.

بعد الدفع، يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد MakeCommerce ذلك: بالإشعار الموقَّع أو بعودة العميل الموقَّعة، مع التحقق من المعاملة عبر واجهة برمجة تطبيقات MakeCommerce. ثم يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your MakeCommerce payment has been received. وإذا وُضع الطلب قيد الانتظار للمراجعة، تعرض الصفحة Your MakeCommerce payment was received and is being reviewed by the shop.

إذا تمت الموافقة على الدفع ولكنه لم يكتمل بعد، أو تعذّر الوصول إلى MakeCommerce، تعرض صفحة Payment confirmation الرسالة We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. مع الزرين Check again وBack to checkout. وينشئ الإشعار الطلب فور اكتمال الدفع.

إذا ألغى العميل في صفحة MakeCommerce، أو انتهت صلاحية الدفع أو فشل، يعود العميل إلى إتمام الطلب مع رسالة، مثل The payment was cancelled. You can try again or choose another payment method. أو The payment session expired. Please try again. أو The payment was not completed. Please try again or choose another payment method. تُحفظ السلة، ويمكن للعميل الدفع مجددًا. وكل محاولة هي معاملة MakeCommerce جديدة. ويظل رابط الدفع الأقدم للسلة نفسها يعمل، ولا يمكن دفع السلة مرتين في طلبين.

إذا تعذّر على MakeCommerce بدء الدفع، يبقى العميل في إتمام الطلب مع الرسالة MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. أو MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. ويُكتب السبب الفني في السجل.

يجري اختيار البنك أو البطاقة في صفحة MakeCommerce وليس في إتمام الطلب بمتجرك. ولا تدعم الوحدة البطاقات المحفوظة أو المدفوعات المتكررة أو الاشتراكات، ولا خدمات الشحن من MakeCommerce (خزائن الطرود والملصقات).

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

حالات الطلب

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

Payment accepted: تم تأكيد الدفع. يُسجَّل الدفع مع معرّف معاملة MakeCommerce، وتعرض ملاحظة المبلغ والمعاملة والبيئة وطريقة التحقق (واجهة برمجة تطبيقات MakeCommerce أو إشعار موقَّع).

MakeCommerce payment on hold: كان المبلغ المدفوع أو العملة مختلفًا عن السلة (على سبيل المثال، تغيّرت السلة بعد بدء الدفع)، أو كان المبلغ مفقودًا، أو لم تكن المعاملة في MakeCommerce نهائية بعد رغم الإبلاغ عن اكتمالها، أو وصل الدفع بعد إلغاء الطلب. وتوضّح الملاحظة السبب. وإذا كانت العملة المدفوعة هي عملة الطلب، فإن المبلغ المدفوع فعلًا يُسجَّل في الطلب. ولا تدفع معاملة بها عدم تطابق الطلب لاحقًا؛ أما المعاملة التي لم تكن نهائية بعد فتُكمل الطلب عندما تبلغ MakeCommerce باكتمالها. تحقّق من المعاملة في Merchant Portal، ثم نفّذ الطلب أو أعد المبلغ.

Refunded: تم رد الدفع بالكامل عبر الوحدة.

إذا وصل دفع ثانٍ لطلب مدفوع بالفعل، لا يتغير الطلب. وتطلب منك ملاحظة استرداد المكرر في Merchant Portal الخاص بـ MakeCommerce.

كتلة الدفع في MakeCommerce

تعرض صفحة الطلب كتلة MakeCommerce payment تضم جميع معاملات MakeCommerce الخاصة بالسلة (التاريخ، ومعرّف المعاملة، وشارة Test للمدفوعات التجريبية، والمبلغ، وحالة MakeCommerce ونتيجتها)، والمبالغ المدفوعة والمستردة، وسجل الاستردادات، وMakeCommerce notes الخاصة بالطلب. ولا تحتاج أزرار الكتلة إلا إلى صلاحية تعديل الطلبات، لا إلى الوصول إلى الوحدات.

Check MakeCommerce payment status: يطلب من واجهة برمجة تطبيقات MakeCommerce حالة معاملات السلة (الأحدث أولًا)، ويطبّقها، ويضيف ملاحظة بالنتيجة. استخدمه عندما يقول العميل إنه دفع لكن الطلب لم يكتمل.

الاستردادات

في كتلة MakeCommerce payment، أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب سببًا اختياريًا، ثم انقر على Refund via MakeCommerce. أكّد السؤال Refund this amount via MakeCommerce? الاستردادات الكاملة والجزئية مدعومة. وتقتصر الاستردادات على مبلغ معاملة MakeCommerce وعملتها، لذلك بعد عدم تطابق المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. ويُرسل الاسترداد إلى البيئة التي تم فيها الدفع (الاختبار أو التشغيل المباشر)، لذلك يجب ضبط مفاتيح تلك البيئة. ويُرسل السبب إلى MakeCommerce بوصفه تعليق الاسترداد؛ وإذا لم يُدخل سبب يكون التعليق Refund for order ومرجع الطلب. وإذا رفضت MakeCommerce الاسترداد، تعرض الكتلة الخطأ، وتُضاف ملاحظة، ولا يُسجَّل أي استرداد. وإذا كانت MakeCommerce ما زالت تعالج الدفع، تكون الرسالة MakeCommerce is still processing this payment — try the refund again later. ويُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع معرّف الاسترداد في MakeCommerce. ويؤدي الاسترداد الكامل إلى تعيين الطلب إلى Refunded. ولا يغيّر الاسترداد الجزئي الحالة. وتتوفر الاستردادات بعد أن تؤكد MakeCommerce الدفع.

لا تنشئ الوحدة إشعارات ائتمان. ولا تعيد أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب أي أموال عبر MakeCommerce.

تصل الاستردادات التي تُجرى في Merchant Portal مع حالة المعاملة، وتُضاف إلى الملاحظات. ولا تتغير حالة الطلب وإشعارات الائتمان تلقائيًا.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox MakeCommerce Payment هي أول كتلة في Modules > Module Manager > VibeFox MakeCommerce Payment > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها السطر Product: presta-payment-makecommerce والرابط 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.

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

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

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

لا تظهر MakeCommerce في إتمام الطلب: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة الحالية لديها مفاتيحها: Test Shop ID وTest Secret key في وضع الاختبار، وLive Shop ID وLive Secret key في وضع التشغيل المباشر. وتحقّق من أن عملة السلة لا تتجاوز خانتين عشريتين. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة، ولبلد العميل، ولمجموعة العميل.

تمّ الدفع لكن لم يُنشأ أي طلب: لم تصل الإشعارات إلى المتجر، مثلًا بسبب جدار حماية أو مصادقة أساسية. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر أو ينقر على Check again. تحقّق من ضبط مفاتيح البيئة التي تم فيها الدفع: يُتحقق من الإشعار باستخدام Secret key لتلك البيئة، وبدونه تتلقى MakeCommerce خطأ وتعيد المحاولة. فعّل Debug log لرؤية الإشعارات.

الطلب في حالة MakeCommerce payment on hold: اقرأ MakeCommerce notes في الكتلة الموجودة في صفحة الطلب (انظر حالات الطلب)، وتحقّق من المعاملة في Merchant Portal، ثم نفّذ الطلب أو أعد المبلغ.

تُرفض الإشعارات: تُرفض الرسالة ذات التوقيع الخاطئ، أو المخصصة لسلة أخرى أو متجر آخر، أو لمعاملة لم تُنشأ للسلة، ولا يتغير شيء. تحقّق من أن Shop ID وSecret key يعودان إلى الحساب نفسه والبيئة نفسها في MakeCommerce.

يرى العميل خطأً عند اختيار MakeCommerce: فعّل Debug log وانظر إلى الحقل Log في صفحة الوحدة. وتعطي العملة التي لا تستطيع MakeCommerce تحصيلها الرسالة MakeCommerce cannot process payments in مع رمز العملة.

يفشل الاسترداد برسالة متعلقة بالبيئة: دُفع الطلب في بيئة الاختبار أو التشغيل المباشر، ومفاتيح تلك البيئة غير مضبوطة. أدخلها وأعد المحاولة.

يفشل الاسترداد برسالة No MakeCommerce transaction ID found for this order: لا يملك الطلب دفعة MakeCommerce مؤكدة. استرده من Merchant Portal.

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

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

MakeCommerce علامة تجارية تعود إلى مالكها. هذه الوحدة غير تابعة لـ MakeCommerce ولا تحظى بتأييدها.