VibeFox 2C2P for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 6.0 أو أحدث، مثبت ومفعّل. بدونه تعرض الإضافة تنبيهًا في لوحة الإدارة ولا تُحمَّل طريقة الدفع.

PHP: 8.0 أو أحدث.

حساب 2C2P: تحتاج إلى Merchant ID ومفتاح Secret Key لحساب التاجر لديك في 2C2P. تصدرهما 2C2P عند فتح حساب التاجر. ولحسابات بيئة الاختبار والإنتاج مفاتيح مختلفة. وتوجد وثائق المطوّرين وبطاقات الاختبار الخاصة ببيئة الاختبار على developer.2c2p.com.

العملة: يجب أن تكون عملة المتجر مدعومة من الإضافة ومفعّلة في حسابك لدى 2C2P. ومن العملات المدعومة، على سبيل المثال، THB وSGD وMYR وPHP وIDR وVND وMMK وKHR وLAK وCNY وHKD وTWD وJPY وKRW وINR وAUD وNZD وUSD وEUR وGBP. وإذا لم تكن عملة المتجر مدعومة، تُخفى طريقة الدفع في صفحة الدفع.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل Merchant ID ومفتاح Secret Key الخاصين ببيئة الاختبار، وفعّل Enable/Disable، ونفّذ طلبًا تجريبيًا.

6. عندما تصبح جاهزًا، أدخل بيانات الاعتماد الخاصة بالإنتاج، وألغِ تحديد Sandbox Mode.

تُرسل عناوين العودة والإشعار مع كل دفعة. ولا حاجة إلى أي إعداد في بوابة 2C2P.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > 2C2P. وتظهر فوق الحقول، ما دام وضع بيئة الاختبار مفعّلًا، الرسالة Sandbox mode is active. No real transactions will be processed. وتحذّرك الصفحة عندما تكون البوابة مفعّلة لكن Merchant ID أو Secret Key للوضع الحالي فارغ، وعندما لا تكون عملة المتجر مدعومة. وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع. وعند الحفظ مع إيقاف Sandbox Mode، تطلب الإضافة Merchant ID ومفتاح Secret Key الخاصين بالإنتاج إذا كانا فارغين.

عام

Enable/Disable: Enable 2C2P Payment Gateway يفعّل طريقة الدفع أو يوقفها. الافتراضي: إيقاف.

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: 2C2P Payment.

Description: النص الذي يظهر تحت طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P. وفي وضع بيئة الاختبار تُضاف إليه (TEST MODE).

وضع بيئة الاختبار (sandbox)

Sandbox Mode: Enable sandbox / test mode يُرسل المدفوعات إلى بيئة اختبار 2C2P (demo2.2c2p.com) باستخدام بيانات الاعتماد الخاصة ببيئة الاختبار أدناه. الافتراضي: مفعّل. ألغِ تحديده لاستقبال مدفوعات حقيقية.

Sandbox Merchant ID: معرّف التاجر الخاص ببيئة الاختبار لدى 2C2P.

Sandbox Secret Key: المفتاح السري الخاص ببيئة الاختبار لدى 2C2P.

بيانات اعتماد واجهة الإنتاج البرمجية

تُستخدم عند إيقاف وضع بيئة الاختبار.

Merchant ID: معرّف التاجر الخاص بالإنتاج لدى 2C2P. مطلوب عند إيقاف وضع بيئة الاختبار.

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

صفحة الدفع

يعرض هذا القسم، للعلم فقط، عنوان العودة في الواجهة الأمامية (https://your-site/?wc-api=tc2p_p) وعنوان الإشعار في الخلفية (https://your-site/?wc-api=tc2p_p&tc2p_p_s2s=1). وتُرسل العناوين تلقائيًا مع كل دفعة.

Payment Page Language: لغة صفحة الدفع لدى 2C2P. الافتراضي: English.

Redirect API version: اتركه على 8.5 ما لم تُبلغك 2C2P بأن حسابك ما زال يستخدم الإصدار القديم 7.0 (توقيعات SHA-1). وتبقى نتائج المدفوعات التي بدأت قبل التغيير قابلة للتحقق.

Order ID prefix: اختياري، ويقبل الأحرف والأرقام فقط (10 كحد أقصى)، مثل SHOP1. ترفض 2C2P رقم طلب سبق أن استلمته. اضبط بادئة فريدة عندما تشارك عدة متاجر حسابًا واحدًا لدى 2C2P، وكذلك في بيئة الاختبار حيث تُشترك حسابات التجار التجريبية. تُحذف الرموز الأخرى عند الحفظ مع تحذير.

الإعدادات المتقدمة

Enable Logging: Log 2C2P events يكتب إلى WooCommerce > Status > Logs، والمصدر wcp_2c2p_payment. لا تُسجَّل بيانات البطاقات ولا المفاتيح السرية. الافتراضي: إيقاف.

Delete Data on Uninstall: Delete the gateway settings, 2C2P order meta and log files when the plugin is deleted. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا 2C2P Payment) ويقدّم الطلب. تعرض الصفحة التالية Thank you for your order. You will be redirected to 2C2P to complete your payment. وتنقل العميل إلى صفحة الدفع الخاصة بـ 2C2P بعد لحظة. وإذا لم يحدث ذلك، ينقر العميل Pay via 2C2P. وتحتوي الصفحة أيضًا على زر Cancel order.

في صفحة 2C2P يدفع العميل بأي طريقة مفعّلة في حسابك لدى 2C2P، مثل البطاقات والمحافظ الإلكترونية ومدفوعات QR والتحويل المصرفي أو المدفوعات النقدية. وتُرسل الإضافة إجمالي الطلب بعملة الطلب، وبريد الفوترة الإلكتروني للعميل، وأسماء المنتجات المطلوبة. ويمكن إتمام الدفع خلال 24 ساعة.

تُبلغ 2C2P بالنتيجة مرتين: يعود متصفح العميل إلى المتجر، وترسل 2C2P إشعارًا من الخادم إلى الخادم. ويُعالَج الاثنان بالطريقة نفسها. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد 2C2P الدفع بتوقيع صالح. ويجب أن تنتمي النتيجة إلى الطلب نفسه: يُتحقق من معرّف التاجر ومفتاح الطلب ورقم الطلب وطريقة الدفع. وتُرفض النتائج التي لا تحمل توقيعًا صالحًا.

بعد دفع ناجح أو معلّق يصل العميل إلى صفحة استلام الطلب، وتُفرَّغ السلة. وإذا لم يكتمل الدفع، يعود العميل إلى صفحة الدفع مع الرسالة Payment was not completed. Please try again or choose a different payment method. ويُلغى الطلب، وتبقى السلة كما هي، ويقدّم العميل طلبًا جديدًا. وإذا تعذّر تأكيد نتيجة الدفع، يرى العميل الرسالة We could not confirm the payment result. If your account was charged, please contact us before paying again.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية وفي كتلة Checkout. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

لا تدعم الإضافة الاسترداد من WooCommerce، ولا حفظ البطاقات، ولا المدفوعات المتكررة أو WooCommerce Subscriptions، ولا حقول البطاقات في موقعك، ولا واجهة 2C2P PGW 4.x البرمجية.

الطلبات

Order statuses

Pending payment: انتقل العميل إلى 2C2P ولم تصل أي نتيجة بعد.

Processing or Completed: أبلغت 2C2P بدفع ناجح (الحالة 000). تضع WooCommerce الطلب في حالة «قيد التنفيذ»، أو «مكتمل» للطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل. وتعرض ملاحظة الطلب معاملة 2C2P ورمز الموافقة والتاريخ وقناة الدفع. ومعرّف المعاملة هو المرجع الخاص بالمعاملة لدى 2C2P.

On hold: الدفع معلّق لدى 2C2P (الحالة 001)، مثل دفعة نقدية لم يسددها العميل بعد. يصبح الطلب مدفوعًا عندما تُبلغ 2C2P بالدفع. ويُوضع الطلب في حالة «في الانتظار» أيضًا عندما تُبلغ 2C2P بمبلغ أو عملة يختلفان عن إجمالي الطلب. وتعرض ملاحظة الطلب القيمتين المستلمة والمتوقعة. راجع الطلب والمعاملة في بوابة 2C2P.

Cancelled: رُفض الدفع أو ألغاه العميل أو فشل (الحالات 002 و003 و999). وتعرض ملاحظة الطلب الحالة والسبب.

لا تغيّر أي نتيجة لاحقة طلبًا مدفوعًا أو مستردًا، ولا تعيد نتيجة قديمة مكررة فتح طلب ألغيته.

الاسترداد

لا يُدعم الاسترداد من WooCommerce. استرد المبلغ من بوابة التاجر في 2C2P، ثم أنشئ استردادًا يدويًا في WooCommerce.

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

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

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

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

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

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

2C2P لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن Merchant ID وSecret Key للوضع الحالي موجودان: حقول بيئة الاختبار في وضع بيئة الاختبار، وحقول الإنتاج في وضع الإنتاج. تحقق من أن عملة المتجر مدعومة. وتعرض صفحة الإعدادات تحذيرًا في الحالتين.

تمت عملية الدفع لكن الطلب ما زال Pending payment: لم تصل إلى متجرك نتيجة صالحة. تحقق من أن Merchant ID وSecret Key للوضع الحالي يطابقان الحساب لدى 2C2P الذي تمت به عملية الدفع، ومن أن Redirect API version يطابق حسابك. تُرفض النتيجة التي تحمل توقيعًا خاطئًا أو معرّف تاجر آخر. فعّل Enable Logging وابحث عن رسائل تحتوي على hash أو merchant ID في WooCommerce > Status > Logs. تحقق أيضًا من أن خادمك يقبل الطلبات القادمة من 2C2P إلى عنوان الإشعار في الخلفية.

تقول 2C2P إن رقم الطلب موجود مسبقًا: ترفض 2C2P رقم الطلب نفسه مرتين. ويحدث هذا عندما تشارك عدة متاجر حسابًا واحدًا لدى 2C2P، أو في بيئة الاختبار حيث تُشترك حسابات التجار التجريبية بين كثير من المطوّرين. اضبط Order ID prefix فريدًا.

تم الدفع لكن الطلب في حالة On hold: إما أن الدفع ما زال معلّقًا لدى 2C2P (مثل دفعة نقدية لم يسددها العميل بعد)، وإما أن المبلغ المدفوع أو العملة لم يطابقا الطلب. راجع ملاحظات الطلب والمعاملة في بوابة 2C2P.

يرى العميل الرسالة This payment method is currently unavailable for this order: عملة الطلب غير مدعومة، أو أن Merchant ID أو Secret Key للوضع الحالي فارغ.

Please enter your live Merchant ID or Please enter your live Secret Key on save: وضع بيئة الاختبار مُوقَف، وأحد حقول الإنتاج فارغ. أدخل بيانات اعتماد الإنتاج أو أبقِ Sandbox Mode مفعّلًا.

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

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

إلغاء تفعيل الإضافة يُبقي جميع البيانات. للإزالة، ألغِ التفعيل ثم احذفها من صفحة Plugins. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالته. أما إعدادات البوابة وبيانات 2C2P المحفوظة في الطلبات وملفات السجل فتُحذف فقط إذا كان Delete Data on Uninstall مفعّلًا، وإلا فتبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات معاملاتها.

2C2P علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ 2C2P ولا تحظى بمصادقتها.