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

المتطلبات

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

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

حساب 2C2P: تحتاج إلى Merchant ID ومفتاح Secret Key لحساب التاجر لديك لدى 2C2P. تصدرهما 2C2P عند فتح حساب التاجر. لحسابي الاختبار (sandbox) والإنتاج مفاتيح مختلفة. وتوجد وثائق المطورين وبطاقات الاختبار الخاصة ببيئة sandbox على 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. في لوحة الإدارة، انتقل إلى Modules > Module Manager واضغط على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، اضغط على Configure، أو ابحث لاحقًا عن VibeFox 2C2P Payment في قائمة الوحدات واضغط على Configure.

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

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

5. عندما تكون جاهزًا، أدخل بيانات الإنتاج وأوقف Sandbox Mode.

عند التثبيت تنشئ الوحدة حالتين للطلب: Awaiting 2C2P payment و2C2P payment on hold. ويفعّل PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييد ذلك في Payment > Preferences. تُرسل عناوين العودة والإشعار مع كل دفعة. ولا حاجة إلى أي إعداد في بوابة 2C2P.

الإعداد

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox 2C2P Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها. وفوق الحقول تعرض الصفحة Sandbox mode is active. No real transactions will be processed. ما دام وضع sandbox مفعّلًا. وتحذّرك عندما تكون البوابة مفعّلة لكن Merchant ID أو Secret Key للوضع الحالي فارغ، وعندما تكون عملة المتجر الافتراضية غير مدعومة. وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع. وإذا حفظت مع إيقاف Sandbox Mode وكان أحد حقول الإنتاج فارغًا، تعرض الوحدة Please enter your live Merchant ID. أو Please enter your live Secret Key. ومع ذلك تُحفظ الإعدادات.

2C2P

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

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

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

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

Sandbox Mode: يرسل المدفوعات إلى بيئة sandbox لدى 2C2P (demo2.2c2p.com) باستخدام بيانات sandbox المذكورة أدناه. الافتراضي: مفعّل. أوقفه لتلقي مدفوعات حقيقية.

Sandbox Merchant ID: Merchant ID الخاص بك في بيئة sandbox لدى 2C2P.

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

بيانات واجهة API للإنتاج

تُستخدم عندما يكون وضع sandbox موقوفًا.

Merchant ID: Merchant ID الخاص بك في بيئة الإنتاج لدى 2C2P.

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

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

مسح الأسرار المحفوظة: ضع علامة على Sandbox Secret Key أو Secret Key ثم اضغط على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة كما هي.

تُتحقق النتائج دائمًا باستخدام Merchant ID ومفتاح Secret Key للوضع الذي تمت فيه الدفعة. تبقى الدفعة التي بدأت في وضع sandbox تُتحقق بمفتاح sandbox حتى بعد التحويل إلى الإنتاج، ويُرفض أي نتيجة موقّعة بمفتاح الوضع الآخر.

صفحة الدفع

عناوين النتائج: تعرض، للاطلاع، Frontend return URL وBackend notification URL. وعند تفعيل الروابط الودية تبدو هكذا: https://your-shop/module/wcp_2c2p_payment/return وhttps://your-shop/module/wcp_2c2p_payment/notify، وقد يسبقها رمز لغة مثل /en/. وتُرسل تلقائيًا مع كل دفعة.

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

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

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

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

Enable Logging: يكتب أحداث 2C2P في logs/tc2p_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل بيانات البطاقات ولا المفاتيح السرية ولا رسائل البريد الإلكتروني للعملاء ولا رموز الدفع. الافتراضي: إيقاف. وما دام موقوفًا لا يُكتب أي شيء، بما في ذلك الأخطاء.

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

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

صفحة الدفع

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

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

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

بعد نجاح الدفع يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية التي تعرض Your 2C2P payment has been received. وللدفعة المعلّقة تعرض الصفحة Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment. وللطلب الموضوع في الانتظار تعرض Your payment was received and is being reviewed by the shop. وإذا أُلغيت الدفعة المعلّقة لاحقًا، تعرض Your 2C2P payment was not completed. Please contact us about this order.

إذا لم تكتمل الدفعة، لا يُنشأ أي طلب. يعود العميل إلى صفحة الدفع مع الرسالة 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. وإذا تعذّر بدء الدفع، مثل حالة عدم دعم عملة السلة، تكون الرسالة This payment method is currently unavailable for this order. Please contact us or choose another payment method.

إذا كان للسلة طلب بالفعل (مدفوع أو في انتظار دفعة معلّقة)، لا يُنشأ نموذج دفع ثانٍ. ويُنقل العميل إلى صفحة تأكيد الطلب.

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

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى 2C2P ولم تصل أي نتيجة بعد، أو فشل الدفع. لا توجد سوى السلة.

Payment accepted: أبلغت 2C2P بنجاح الدفع (الحالة 000). تُسجَّل الدفعة بمرجع معاملة 2C2P كمعرّف للمعاملة. وتعرض ملاحظة خاصة في الطلب معاملة 2C2P ورمز الموافقة والتاريخ وقناة الدفع.

Awaiting 2C2P payment: الدفعة معلّقة لدى 2C2P (الحالة 001)، مثل دفعة نقدية لم يسددها العميل بعد. ينتقل الطلب إلى Payment accepted عندما تبلغ 2C2P بالدفع.

2C2P payment on hold: أبلغت 2C2P بمبلغ أو عملة تختلف عن إجمالي الطلب. تعرض الملاحظة القيم المستلمة والمتوقعة. تحقّق من الطلب والمعاملة في بوابة 2C2P.

Canceled: رُفضت الدفعة المعلّقة أو أُلغيت أو فشلت لاحقًا (الحالات 002 و003 و999). تعرض الملاحظة الحالة والسبب. ولا تُلغي نتيجة فشل لمحاولة أقدم طلبًا أنشأته محاولة أخرى.

لا يتغير الطلب المدفوع أبدًا بنتيجة لاحقة، ولا تعيد نتيجة قديمة مكررة فتح طلب ألغي. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك الملاحظة التحقق من ذلك واسترداد المبلغ المكرر من بوابة التاجر في 2C2P.

كتلة الدفع لدى 2C2P

تعرض صفحة الطلب كتلة 2C2P payment تتضمن رقم الطلب لدى 2C2P، والمعاملة، وحالة الدفع، والقناة، ورمز الموافقة، ورقم البطاقة بعد إخفاء أرقامها، والتاريخ، واستجابة القناة، والمبلغ المستلم، إضافة إلى شارة Sandbox للمدفوعات التجريبية.

الاسترداد

لا يُدعم الاسترداد من PrestaShop. استرد الدفعة من بوابة التاجر في 2C2P، ثم سجّل الاسترداد يدويًا في PrestaShop.

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

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

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

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

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

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

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

يرد إشعار الواجهة الخلفية بـ 400 FAIL: تنقص النتيجة بعض الحقول، أو التوقيع خاطئ، أو Merchant ID مختلف، أو الرمز غير صحيح. وتعني 404 FAIL أن رقم الطلب لدى 2C2P لم يُصدره هذا المتجر. وتعني 503 RETRY أن الطلب كان يُؤكَّد بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة)؛ وستعيد 2C2P المحاولة لاحقًا. فعّل Enable Logging لمعرفة السبب.

يعرض عنوان الإشعار FAIL في المتصفح: هذا طبيعي. يقبل العنوان طلبات POST الصادرة من 2C2P فقط.

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

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

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

عند الحفظ تظهر الرسالة Please enter your live Merchant ID أو Please enter your live Secret Key: وضع sandbox موقوف وأحد حقول الإنتاج فارغ. أدخل بيانات الإنتاج أو أبقِ Sandbox Mode مفعّلًا.

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

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

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