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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبت ومفعّل. وبدون WooCommerce ترفض الإضافة التفعيل.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة وانقر على Install Now. يمكنك أيضًا رفع مجلد wcp_makecommerce_payment إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > MakeCommerce > Manage، أو انقر على Settings أسفل اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox الخاص بك في مربع الترخيص أعلى الصفحة وانقر على Activate.

5. أدخل Shop ID وSecret key لبيئة الاختبار، وللمدفوعات الحقيقية أدخل المفاتيح الحية (انظر التهيئة). ولا يلزم تهيئة أي شيء في Merchant Portal.

6. فعّل خيار Enable/Disable. اختبر عملية دفع مع تفعيل Test mode، ثم ألغِ تحديده لقبول المدفوعات الحقيقية.

التهيئة

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

General

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 account

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

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

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

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

Live Shop ID: معرف المتجر لحسابك الحي.

Live Secret key: المفتاح السري لحسابك الحي.

Payment notifications

لا يلزم تهيئة أي شيء في Merchant Portal. وتحمل كل معاملة عناوين URL الخاصة بها للعودة والإلغاء والإشعار، بالاعتماد على العنوان المعروض في هذا القسم (يشبه https://your-site/wc-api/wc_mkc_payment/) مع إضافة رقم الطلب ومفتاح الطلب. وترسل MakeCommerce رسالة موقَّعة إلى عنوان URL للإشعار (من خادم إلى خادم) وعبر متصفح العميل إلى عنوان URL للعودة أو الإلغاء. ويجري التحقق من التوقيع باستخدام Secret key للبيئة التي أُنشئت فيها المعاملة. وتُرفض الرسائل التي لا تحمل توقيعًا صالحًا.

تتعامل الإضافة مع حالات معاملات MakeCommerce التالية:

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

Advanced

Debug log: يكتب خيار Log API calls and payment notifications التفاصيل في WooCommerce > Status > Logs، المصدر wcp_makecommerce_payment. وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: معطّل.

Delete data: خيار Delete the gateway settings and logs when the plugin is deleted. ويجري الاحتفاظ بالطلبات وملاحظات الدفع الخاصة بها دائمًا. ولا يؤدي تعطيل الإضافة إلى حذف أي شيء أبدًا. الافتراضي: معطّل.

إتمام الطلب

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

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

إذا ألغى العميل العملية في صفحة MakeCommerce أو انتهت صلاحية الدفع، يعود العميل إلى صفحة إتمام الطلب (أو إلى صفحة Pay for order) مع رسالة، على سبيل المثال The payment was cancelled. You can try again or choose another payment method. أو The payment session expired. Please try again. وإذا تعذر تأكيد الدفع بعد، تكون الرسالة We could not confirm your payment yet. If you completed it, your order will be updated automatically; otherwise please try again. ويمكن للعميل الدفع مجددًا. ويظل رابط الدفع الأقدم للطلب نفسه صالحًا للعمل، ولا يمكن دفع قيمة الطلب مرتين.

إذا لم تتمكن 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. ويُضاف السبب التقني إلى ملاحظات الطلب والسجل.

تعمل طريقة الدفع مع صفحة إتمام الطلب التقليدية، وفي كتلة إتمام الطلب، وفي صفحة Pay for order. وهي متوافقة مع التخزين عالي الأداء للطلبات (HPOS) في WooCommerce.

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

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

حالات الطلب

Pending payment: تم توجيه العميل إلى MakeCommerce ولم يدفع بعد، أو لم تؤكد MakeCommerce الدفع بعد. وتعرض ملاحظة الطلب معاملة MakeCommerce والمبلغ والبيئة.

Processing: تم تأكيد الدفع. وتتحول الطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل إلى مكتمل، وهو الوضع الافتراضي في WooCommerce. وتعرض ملاحظة الطلب المبلغ والمعاملة والبيئة وكيفية التحقق منها (واجهة برمجة تطبيقات MakeCommerce أو إشعار موقَّع). ومعرف المعاملة هو معرف معاملة MakeCommerce.

On hold: اختلف المبلغ المدفوع أو العملة عن الطلب، أو كان المبلغ مفقودًا، أو لم تكن حالة المعاملة في MakeCommerce نهائية بعد، أو وصل الدفع لطلب ملغى. وتوضح ملاحظة الطلب ذلك. ولا تؤدي مثل هذه المعاملة إلى اعتبار الطلب مدفوعًا لاحقًا أبدًا. تحقق من المعاملة في Merchant Portal وأكمل الطلب أو استرده يدويًا.

Failed: أُلغيت أحدث دفعة للطلب، أو انتهت صلاحيتها، أو فشلت. ويمكن للعميل محاولة الدفع مرة أخرى.

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

Check MakeCommerce payment status

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

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ وانقر على Refund via Bank link or card (MakeCommerce) (يعرض الزر قيمة Title الخاصة بك). وتدعم الإضافة الاستردادات الكاملة والجزئية. ويُرسل الاسترداد إلى البيئة التي دُفع فيها الطلب (اختبار أو إنتاج)، لذا يجب ضبط مفاتيح تلك البيئة. وإذا لم تقبل MakeCommerce الاسترداد، يعرض WooCommerce الخطأ وتُضاف ملاحظة ولا يُسجل أي استرداد. وإذا كانت MakeCommerce لا تزال تعالج الدفع، تكون الرسالة MakeCommerce is still processing this payment — try the refund again later. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرف استرداد MakeCommerce.

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. ويوجد مربع الترخيص في أعلى WooCommerce > Settings > Payments > MakeCommerce. الصق المفتاح في License key وانقر على Activate. ويعرض المربع الحالة، مثل التاريخ الذي يظل فيه الترخيص نشطًا ونطاقك. استخدم Check now للتحقق من الحالة مجددًا، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. ويفتح الرابط Manage licenses and domains in your account حسابك على vibefox.net.

يعمل المفتاح الواحد على نطاق واحد. ولا تؤدي إزالة المفتاح من موقع إلى تحرير خانة النطاق الخاصة به. حرر الخانة في حسابك على vibefox.net.

بدون مفتاح نشط، لا تظهر MakeCommerce للعملاء عند إتمام الطلب. وإذا بدأ الدفع على أي حال، يرى العميل This payment method is not available. Please choose another one. ولا يزال بإمكان مديري المتجر المسجلين رؤية طريقة الدفع مميزة بالرمز (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. ويظهر تذكير في صفحة الإضافات وصفحات WooCommerce. ولا تتأثر الطلبات الحالية: فالمدفوعات التي بدأت بالفعل يستمر تأكيدها، وتعمل الاستردادات دون مشاكل.

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

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

لا تظهر MakeCommerce عند إتمام الطلب: تأكد من أن الترخيص نشط، وأن خيار Enable/Disable مفعّل، وأن البيئة الحالية تحتوي على مفاتيحها: Test Shop ID وTest Secret key في وضع الاختبار، وLive Shop ID وLive Secret key في وضع التشغيل المباشر. تأكد من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) تحتوي على منزلتين عشريتين على الأكثر. وتعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشاكل.

تم الدفع بنجاح، لكن الطلب يظل في حالة في انتظار الدفع: تعذر وصول الإشعارات إلى الموقع، بسبب جدار حماية أو وضع الصيانة أو المصادقة الأساسية مثلًا. افتح الطلب وشغّل إجراء الطلب Check MakeCommerce payment status. تأكد من ضبط مفاتيح البيئة التي تم الدفع فيها: حيث يجري التحقق من الإشعار باستخدام Secret key لتلك البيئة، وبدونه تتلقى MakeCommerce خطأً وتعيد المحاولة.

الطلب في حالة قيد الانتظار مع ملاحظة من MakeCommerce: لم يتطابق الدفع مع الطلب (المبلغ، العملة، الحالة) أو وصل لطلب ملغى. تحقق من المعاملة في Merchant Portal وأكمل الطلب أو استرده يدويًا.

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

يرى العميل خطأ عند إتمام الطلب: افتح ملاحظات الطلب أو فعّل Debug log وراجع WooCommerce > Status > Logs، المصدر wcp_makecommerce_payment. وتُرجع العملة التي لا تستطيع MakeCommerce تحصيلها العبارة MakeCommerce cannot process payments in متبوعة برمز العملة.

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

فشل الاسترداد مع رسالة No MakeCommerce transaction ID found for this order: لا يحتوي الطلب على معاملة MakeCommerce. استرد المبلغ عبر Merchant Portal.

يعرض مربع الترخيص خطأ: اتبع الرسالة الواردة في المربع. على سبيل المثال، إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، فحرر خانة في حسابك على vibefox.net وانقر على Check now. وإذا تغير عنوان الموقع، فانقر على Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل وفقًا لآخر حالة معروفة.

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

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

MakeCommerce هي علامة تجارية لمالكها المعني. هذه الإضافة غير تابعة لـ MakeCommerce أو معتمدة منها.