VibeFox Peach Payments for OpenCart — المساعدة
المتطلبات
OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).
PHP: 8.0 أو أحدث، مع امتداد OpenSSL (يُستخدم لفك تشفير webhooks).
العملة: يجب أن تكون عملة الدفع للعميل ZAR أو KES أو MUR، لذلك يحتاج متجرك إلى عملة واحدة على الأقل من هذه العملات في System > Localisation > Currencies. وبالنسبة للعملاء الذين يدفعون بعملات أخرى تُخفى طريقة الدفع. وتُحذّرك صفحة الإعدادات عندما لا تكون العملة الافتراضية للمتجر واحدة منها.
حساب Peach Payments: تحتاج إلى بيانات اعتماد Card API لحساب Peach Payments: Entity ID وAccess Token. تأتي بيانات اعتماد الاختبار من لوحة sandbox الخاصة بـ Peach Payments، أما بيانات اعتماد الإنتاج فتأتي من لوحة Peach Payments؛ وهما مختلفتان. وللـ webhooks تحتاج أيضًا إلى مفتاح فك تشفير webhooks، ترسله Peach Payments إليك عند تفعيل Card webhooks لمتجرك (انظر الإعدادات). ويجب أن يكون متجرك متاحًا عبر الإنترنت لاستقبال الـ webhooks.
مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد.
التثبيت
التنزيل ملف zip واحد يحتوي على حزم الإصدارين من OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt وحزمة OpenCart 3 wcp_peach_pay-oc3-(version).ocmod.zip وحزمة OpenCart 4 wcp_peach_pay.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.
OpenCart 3
1. في لوحة الإدارة انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_peach_pay-oc3-(version).ocmod.zip. لا تحتوي الإضافة على أي تعديلات OCMOD، لذلك لا يلزم تحديث Extensions > Modifications. وبدلًا من أداة التثبيت يمكنك نسخ محتويات المجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.
2. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox Peach Payments Pay Gateway وانقر على Install (الزر الأخضر +). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.
3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات. ألصق مفتاح ترخيص VibeFox في الحقل License key ضمن كتلة الترخيص في أعلى الصفحة، ثم انقر على Activate (انظر مفتاح الترخيص).
4. أدخل Entity ID وAccess Token التجريبيين من لوحة sandbox الخاصة بـ Peach Payments، واطلب من Peach Payments تفعيل Card webhooks للعنوان URL الخاص بالـ webhook المعروض في صفحة الإعدادات (انظر الإعدادات).
5. فعّل Enable/Disable ثم انقر على Save. أبقِ Test mode مفعّلًا وأجرِ دفعة باستخدام بطاقة اختبار sandbox من Peach Payments بالعملة ZAR أو KES أو MUR. ثم عطّل Test mode، وأدخل بيانات اعتماد الإنتاج ومفتاح webhook الخاص بالإنتاج، وانقر على Save.
OpenCart 4
1. في لوحة الإدارة انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_peach_pay.ocmod.zip. لا تُغيّر اسم الملف: يستمد OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي يُعاد تسميتها لا تعمل.
2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (الزر الأخضر +) بجوارها.
3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Peach Payments Pay Gateway، وانقر على Install (الزر الأخضر +)، ثم على Edit (زر القلم).
4. أدخل مفتاح الترخيص وبيانات اعتماد Peach Payments والـ webhook كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو عنوان الـ webhook (راجع Webhook).
تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.
الإعدادات
جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Peach Payments Pay Gateway > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ زر Save الموجود أسفل القائمة الصفحة كاملةً. تعرض الصفحة فوق الإعدادات تنبيهات: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.؛ وخطأً عند غياب Entity ID أو Access Token للوضع الحالي (وحتى ذلك الحين لا تظهر طريقة الدفع في صفحة الدفع)؛ وتحذيرًا عند غياب مفتاح فك تشفير webhooks للوضع الحالي (وعندها لا تُؤكَّد المدفوعات إلا عند عودة العميل إلى المتجر)؛ وإشعارًا عندما لا تكون العملة الافتراضية للمتجر مدعومة (وعندها لا تُعرض طريقة الدفع إلا للعملاء الذين يدفعون بعملة مدعومة). وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.
عند الحفظ، يجب ألا يكون الحقل Title فارغًا أو أطول من 128 حرفًا (تعرض الصفحة Enter a title for the payment method (up to 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (القيم السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0، ويجب أن توجد المنطقة الجغرافية وحالات الطلب. وإلا فلن يُحفظ شيء. تُحذف المسافات من بيانات الاعتماد. ويُحفظ مفتاح webhook الذي ليس قيمة سداسية عشرية من 64 حرفًا، أو قائمة فارغة من علامات البطاقات، مع تحذير.
Peach Payments
Enable/Disable: يؤدي Enable Peach Payments إلى تفعيل طريقة الدفع أو تعطيلها. الافتراضي: معطّل.
Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع، وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Credit / Debit Card (Peach Payments). حقل مطلوب، بحد أقصى 128 حرفًا.
Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد، بجوار أيقونة بطاقة. الافتراضي: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
Sort Order: موضع Peach Payments بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.
Geo Zone: اعرض Peach Payments فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.
Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب حتى يُعرض Peach Payments. اتركه فارغًا لعرضه بأي مبلغ.
بيانات اعتماد API
يظهر Access Token وEntity ID الخاصان بـ Card API في لوحة Peach Payments (أما بيانات اعتماد الاختبار فتظهر في لوحة sandbox). يحتوي هذا القسم على روابط إلى اللوحتين وإلى وثائق المطورين لدى Peach Payments.
Test mode: يرسل المدفوعات الجديدة إلى sandbox الخاصة بـ Peach Payments ببيانات الاعتماد التجريبية، ولا يُخصم أي مبلغ حقيقي. عطّله لقبول مدفوعات حقيقية ببيانات اعتماد الإنتاج. وتُتحقق المدفوعات التي بدأت في وضع معين دائمًا في ذلك الوضع، حتى بعد التبديل. الافتراضي: مفعّل. وطالما كان مفعّلًا يرى العميل في خطوة Confirm Order الرسالة Test mode: no real payment will be made.
Test Entity ID: الـ Entity ID (قناة 3-D Secure) لحساب sandbox الخاص بك.
Test Access Token: رمز الوصول (bearer) لحساب sandbox الخاص بك.
Test Webhook Decryption Key: المفتاح السداسي العشري المكوّن من 64 حرفًا الذي يُستخدم لفك تشفير Card webhooks الخاصة بـ sandbox.
Live Entity ID: الـ Entity ID (قناة 3-D Secure) لحساب الإنتاج الخاص بك.
Live Access Token: رمز الوصول (bearer) لحساب الإنتاج الخاص بك.
Live Webhook Decryption Key: المفتاح السداسي العشري المكوّن من 64 حرفًا الذي يُستخدم لفك تشفير Card webhooks الخاصة بحساب الإنتاج.
لا تُعرض رموز الوصول ومفاتيح الـ webhook المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف قيمة محفوظة، حدّد Clear the saved value on save أسفل الحقل ثم انقر على Save.
Webhook
تؤكد الـ webhooks المدفوعات حتى عندما يغلق العميل المتصفح قبل العودة إلى المتجر. يعرض الحقل Webhook URL العنوان URL للـ webhook الخاص بمتجرك. يبدو بالشكل https://your-store/index.php?route=extension/payment/wcp_peach_pay/webhook في OpenCart 3، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_peach_pay/payment/wcp_peach_pay.webhook. ويُنشأ من عنوان واجهة المتجر لتثبيت OpenCart لديك. انسخ العنوان تمامًا كما تعرضه الإعدادات. واطلب من Peach Payments (support@peachpayments.com) تفعيل Card webhooks لحسابك بهذا العنوان، ثم أدخل مفتاح فك التشفير الذي تستلمه في الحقل Webhook Decryption Key الخاص بالوضع نفسه.
تُشفّر Peach Payments كل webhook (AES-256-GCM). ويُرفض أي webhook لا يمكن فك تشفيره بمفتاح الاختبار أو الإنتاج، لذلك لا يستطيع أحد غير Peach Payments تغيير طلباتك. ولا يُطبَّق webhook فُكّ تشفيره بمفتاح وضع معين إلا على المدفوعات التي بدأت في ذلك الوضع. وتستخدم الإضافة إشعارات الدفع التالية:
تُرد الإشعارات الأخرى، مثل إشعار الاختبار الذي يُرسل عند تفعيل الـ webhook، بالرد ignored. ومن دون مفتاح الـ webhook لا يحصل الطلب على حالة إلا عندما يعود العميل إلى المتجر بعد الدفع.
نموذج الدفع
Card brands: العلامات التجارية التي تظهر في نموذج Peach Payments: Visa وMastercard وAmerican Express وDiners Club. اختر فقط العلامات المفعّلة لـ Entity ID الخاص بك. الافتراضي: Visa وMastercard. وإذا لم تُحدَّد أي علامة، يعرض الحفظ تحذيرًا ويعرض النموذج Visa وMastercard.
الطلبات
يُنشأ الطلب في خطوة Confirm Order بلا حالة (طلب مفقود)، ولا يحصل على حالة إلا بعد أن تؤكد Peach Payments الدفع. ويترك الدفع المرفوض أو المتروك الطلب بلا حالة، وتُحتفظ بسلة التسوق. تعرض كل خانة أدناه حالات طلبات OpenCart لديك.
Order Status After Payment: تُضبط عندما تؤكد Peach Payments الدفع ويطابق المبلغ والعملة. الافتراضي: Processing.
Awaiting Payment Status: أبلغت Peach Payments عن دفعة غير متزامنة تنتظر تأكيدًا؛ ويؤكدها الـ webhook لاحقًا. الافتراضي: Pending، لأن OpenCart لا يحتوي على حالة On hold. يمكنك إنشاء حالة خاصة بك من System > Localisation > Order Statuses واختيارها هنا.
On Hold (Review) Status: مراجعة يدوية: المبلغ المدفوع أو العملة لا يطابقان الطلب، أو وصلت الدفعة بعد إلغاء الطلب. وتوضح ملاحظة السبب. الافتراضي: Pending.
Payment Failed Status: تُضبط عندما تُرفض الدفعة غير المتزامنة التي كان الطلب ينتظرها. ولا تزال الدفعة الناجحة اللاحقة تُكمل الطلب. الافتراضي: Failed.
Canceled Status: لا تضبطها الإضافة. تضع الدفعة لطلب في هذه الحالة الطلب قيد المراجعة بدلًا من إعادة فتحه. الافتراضي: Canceled.
Refunded Status: لا تضبطها الإضافة. تُسجَّل الدفعة المستلمة لطلب في هذه الحالة كملاحظة فقط، ولا يتغير الطلب. الافتراضي: Refunded.
متقدم
Logging: يسجل طلبات API ونتائج الدفع في الملف peach_p_debug.log.php داخل مجلد السجلات في OpenCart (storage/logs). لا يمكن قراءة الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى peach_p_debug.old.log.php. وتُسجَّل الأخطاء والتحذيرات دائمًا. ولا تحتوي السجلات على بيانات بطاقات أو مفاتيح أو بيانات عملاء. الافتراضي: معطّل.
Log: يعرض حجم السجل وأحدث إدخالاته. انقر على Clear log لتفريغه.
Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. أما بيانات Peach Payments الخاصة بالطلبات (محاولات الدفع ومعرّفات الدفع) فتُحفظ، لأنها تنتمي إلى الطلبات. الافتراضي: معطّل.
الاستيراد / التصدير
Export: يحفظ Download JSON الإعدادات في ملف JSON. ولا تُصدَّر رموز الوصول ومفاتيح الـ webhook.
Import: ألصق ملف JSON المُصدَّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى رموز الوصول ومفاتيح الـ webhook المحفوظة كما هي.
الدفع
في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit / Debit Card (Peach Payments)). وفي خطوة Confirm Order يرى العميل أيقونة بطاقة ووصفك؛ ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. عندما ينقر العميل على Confirm Order، تُعدّ الإضافة عملية دفع Peach Payments بمبلغ الطلب بعملة الطلب، وتفتح صفحة الدفع Peach Payments payment في متجرك مع Please enter your card details to complete the payment: ونموذج البطاقة الخاص بـ Peach Payments وعلامات البطاقات المحددة، بلغة العميل متى كانت Peach Payments تدعمها. وفي وضع الاختبار تعرض الصفحة Test mode: use a Peach Payments test card, no real payment will be made. تُدخل بيانات البطاقة في نموذج Peach Payments، ويُحمَّل نص النموذج مع تجزئة Subresource Integrity. ويعيد الرابط Choose another payment method إلى صفحة الدفع. وإعادة تحميل الصفحة تعيد استخدام عملية الدفع نفسها لمدة تصل إلى 25 دقيقة، ما لم يتغير إجمالي الطلب. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.
بعد الدفع يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا عندما تؤكد Peach Payments ذلك: يقرأ المتجر نتيجة عملية الدفع لهذا الطلب من واجهة Peach Payments البرمجية، في الوضع الذي أُنشئت فيه عملية الدفع، ويتحقق من أن الدفعة تخص هذا الطلب. ويفعل الـ webhook الشيء نفسه بشكل مستقل؛ فأيهما يصل أولًا يضبط حالة الطلب، والآخر لا يغيّر شيئًا. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وفي OpenCart 4، عند عودة العميل من صفحة 3-D Secure لدى البنك، تفتح صفحة وسيطة قصيرة عنوان الرجوع في متجرك من جديد، فتبقى السلة وتسجيل دخول العميل محفوظين.
إذا لم تكتمل عملية الدفع، يعود العميل إلى صفحة الدفع برسالة ويمكنه المحاولة مرة أخرى: Payment failed: يتبعها السبب الذي تذكره Peach Payments، ثم Please try again or use another card.، أو The payment was not completed. Please try again. وتُحتفظ بسلة التسوق. وإذا لم يكن بالإمكان تأكيد النتيجة بعد (مثلًا لأن Peach Payments لم ترد، أو لأن الـ webhook يعالج السلة نفسها في تلك اللحظة)، فالرسالة هي We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. وعندما لا يوجد مفتاح webhook مضبوط لوضع الدفع، يُطلب من العميل التواصل معك بدلًا من ذلك. وفي OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع.
في OpenCart 3 ينشئ OpenCart طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، وفي OpenCart 4 يُحدَّث طلب الدفع، لكن سلة التسوق تُدفع مرة واحدة فقط: فإذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل، ينتقل العميل مباشرة إلى صفحة النجاح. ويُعدّ أي تغيير في السلة، بما في ذلك الكمية الجديدة، سلةً جديدة تحتاج إلى دفعة خاصة بها.
في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تُعرض صفحة النجاح. وبعد محاولة مرفوضة يدفع العميل الطلب نفسه مرة أخرى عبر عملية دفع جديدة من Peach Payments. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا فشلت دفعته المعلّقة أو ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. وتدفع خطوة Confirm Order التالية طلبًا جديدًا. وإذا كان الطلب قد دُفع ثم أُلغي أو استُرد من المتجر، تكون الرسالة This order was cancelled or refunded by the store. Please contact the store about its payment, or confirm the order again: the cart will be paid with a new order.
إذا تعذّر تجهيز نموذج الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (بيانات اعتماد مفقودة أو غير صحيحة)، أو رسالة تفيد بأن مزوّد الدفع لم يقبل بعض بيانات الفوترة، أو The payment form could not be loaded. Please try again in a moment. ويُكتب السبب التقني في السجل.
يعمل الـ webhook أيضًا عندما يكون المتجر في وضع الصيانة، لأن OpenCart يسمح بمرور طلبات إضافات الدفع. وفي OpenCart 4 تضيف الإضافة إجراء بدء تشغيل خاصًا بها، يسمح بمرور الـ webhook وعودة العميل من Peach Payments.
لا تحتوي الإضافة على نموذج بطاقة في خطوة الدفع نفسها، ولا بطاقات محفوظة، ولا اشتراكات، ولا تفويض مسبق يتبعه تحصيل، ولا طرق EFT أو BNPL أو QR أو أي طرق أخرى غير البطاقات.
الطلبات
حالات الطلب
بلا حالة (طلب مفقود): لم يدفع العميل، أو رُفض الدفع أو لم يكتمل، أو لم تؤكده Peach Payments بعد. يمكن للعميل أن يدفع مرة أخرى. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط فلتر Order Status على Missing Orders. وفي OpenCart 4.1 قد يحمل مثل هذا الطلب الحالة Voided أيضًا، التي يضبطها OpenCart عند عرض خطوة التأكيد مرة أخرى؛ وتعدّه الإضافة طلبًا بلا حالة.
Order Status After Payment (default Processing): تم تأكيد الدفع ويطابق المبلغ والعملة الطلب. تعرض ملاحظة رمز نتيجة Peach Payments ووصفها ومعرّف الدفع. وإذا وضعت Peach Payments علامة مراجعة يدوية على الدفعة، فإن الملاحظة تطلب منك التحقق منها في لوحة Peach Payments قبل الشحن.
Awaiting Payment Status (default Pending): أبلغت Peach Payments عن دفعة تنتظر تأكيدًا. ثم ينقل الـ webhook الطلب إلى Order Status After Payment أو إلى Payment Failed Status.
On Hold (Review) Status (default Pending): المبلغ المدفوع أو العملة لا يطابقان الطلب (ملاحظة amount/currency mismatch — manual review required)، أو وصلت الدفعة بعد إلغاء الطلب. تحقق من الدفعة في لوحة Peach Payments، ثم عالج الطلب أو استرد الدفعة.
Payment Failed Status (default Failed): رفضت Peach Payments الدفعة التي كان الطلب المعلق ينتظرها. ولا تغيّر محاولة مرفوضة طلبًا مدفوعًا أو قيد المراجعة أبدًا.
إذا نجحت دفعة ثانية لطلب مدفوع بالفعل، أو دفعة لطلب آخر من سلة مدفوعة بالفعل، فلن يتغير الطلب المدفوع. وتوضح ملاحظة أن هذه دفعة مكررة وتطلب استردادها في لوحة Peach Payments. وتُسجَّل الدفعة التي تصل لطلب مُسترد كملاحظة فقط على الطلب.
الملاحظات إدخالات في History الطلب لا يراها العميل.
تبويب VibeFox Peach Payments Pay Gateway
في Sales > Orders افتح طلبًا مدفوعًا عبر Peach Payments. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب الإضافة Payment ID مع تسمية Test mode لمدفوعات الاختبار، وCheckout ID، وMerchant transaction ID، وAmount sent to Peach Payments، وResult مع رمز النتيجة، وPeach Payments notes الخاصة بالطلب. ويظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.
الاسترداد
الاستردادات من OpenCart غير متاحة. استرد الدفعة في لوحة Peach Payments وسجّلها في OpenCart عند الحاجة. ومع إعداد الـ webhook، تُضاف الاستردادات والعمليات العكسية واستردادات المبالغ التي تتم في Peach Payments إلى ملاحظات الطلب مع المبلغ والمعرّف؛ ولا تتغير حالة الطلب. أما مرتجعات المنتجات في Sales > Returns فلا تعيد الأموال عبر Peach Payments.
مفتاح الترخيص
تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Peach Payments Pay Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Peach Payments Pay Gateway > Edit، فوق الإعدادات. ألصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-peach والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).
إذا لم يُقبل المفتاح، تُبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.
يعمل المفتاح الواحد على نطاق واحد: عنوان المتجر من إعدادات OpenCart. ولا تؤدي إزالة المفتاح من المتجر إلى تحرير خانة النطاق. حرّر الخانة من حسابك في vibefox.net.
من دون مفتاح نشط لا يُعرض Peach Payments للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. ويظل مستخدم الإدارة المسجّل دخوله إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، معلّمة بـ (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. في OpenCart 4 لا تتوفر هذه المعاينة: فالمتجر لا يرى تسجيل دخول الإدارة، لذلك تُخفى طريقة الدفع عن الجميع دون مفتاح نشط. وبعد أن تفتح صفحة Edit مرة واحدة يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. ولا تتأثر الطلبات الحالية: فالدفعات التي بدأت بالفعل تظل تُؤكَّد بعودة العميل والـ webhook.
عندما تنتهي صلاحية الترخيص تواصل الإضافة العمل، لكن التحديثات والدعم يتطلبان التجديد. تُعاد مراجعة الحالة تلقائيًا عند فتح Dashboard أو صفحة Edit في لوحة الإدارة: مرة واحدة يوميًا خلال أول 14 يومًا بعد إدخال المفتاح، ثم مرة أسبوعيًا. ولا حاجة إلى أي cron job. ويؤدي إلغاء تثبيت الإضافة دائمًا إلى إزالة مفتاح الترخيص وحالة الترخيص.
استكشاف الأخطاء وإصلاحها
لا يظهر Peach Payments في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Entity ID وAccess Token للوضع الحالي مُدخلان (Test Entity ID وTest Access Token في وضع الاختبار، وLive Entity ID وLive Access Token في وضع الإنتاج)، وأن العميل يدفع بالعملة ZAR أو KES أو MUR. تحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات. وتحدد التنبيهات في أعلى الإعدادات المشكلة.
تمت عملية الدفع لكن الطلب يبقى بلا حالة: لم يعد العميل إلى المتجر ولم يصل الـ webhook. تحقق من أن Peach Payments فعّلت Card webhooks للعنوان URL المعروض في الإعدادات تمامًا، وأن Webhook Decryption Key الخاص بالوضع الذي تمت فيه عملية الدفع مُدخل، وأنه لا يوجد جدار حماية أو حماية بكلمة مرور تمنع العنوان. فعّل Logging وانظر إلى الحقل Log للعثور على الـ webhooks المرفوضة.
يرد الـ webhook بـ Decryption failed: تعذّر فك تشفير الـ webhook بمفتاح الاختبار أو الإنتاج. المفتاح غير صحيح أو يتبع حسابًا أو وضعًا آخر. أدخل المفتاح الذي أرسلته Peach Payments لعنوان الـ webhook هذا.
يرد الـ webhook بـ Webhook key not configured: لم يُضبط أي مفتاح webhook أو أن المفتاح غير صالح. أدخل المفتاح المكوّن من 64 حرفًا. ستعيد Peach Payments إرسال الـ webhook لاحقًا.
يرد الـ webhook بـ Busy, retry later: كانت السلة تُعالج بعودة العميل في اللحظة نفسها. لم يتغير شيء، وستعيد Peach Payments إرسال الـ webhook. ويوضح السجل السبب.
يرد الـ webhook بـ Missing or malformed data: لم يكن في الطلب جسم مشفّر أو الترويسات X-Initialization-Vector / X-Authentication-Tag، مثلًا لأن وكيلًا (proxy) غيّرها. لم يتغير شيء.
يرد الـ webhook بـ ignored: الإشعار أصلي، لكنه لا ينتمي إلى عملية دفع لهذا المتجر (متجر آخر يستخدم Entity ID نفسه)، أو جاء من وضع غير وضع الدفعة. لم يتغير شيء.
يعرض عنوان URL للـ webhook Method not allowed في المتصفح: هذا طبيعي. فالعنوان يقبل الطلبات الصادرة من Peach Payments فقط.
يرى العميل The payment form is not available right now: Access Token أو Entity ID للوضع الحالي غير صحيح. تحقق من بيانات الاعتماد والوضع، واقرأ السجل لمعرفة رمز Peach Payments.
يرى العميل The payment session was not found. Please confirm the order again.: فُتحت صفحة الدفع لطلب لم يعد الطلب الحالي للعميل، أو عُطّلت طريقة الدفع في هذه الأثناء. يجب على العميل تأكيد الطلب مرة أخرى.
الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب الإضافة. كان المبلغ المدفوع أو العملة مختلفًا عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. تحقق من الدفعة في لوحة Peach Payments، ثم عالج الطلب أو استرد الدفعة.
يظهر عند الحفظ أن مفتاح الـ webhook يجب أن يكون المفتاح السداسي العشري المكوّن من 64 حرفًا: القيمة ليست المفتاح الخاص بـ Peach Payments. ولا يمكن فك تشفير الـ webhooks حتى تُصحَّح.
إلغاء التثبيت
انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Peach Payments Pay Gateway. تُزال دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. ويزيل OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Orders، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. وإذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان والوصف ووضع الاختبار وبيانات الاعتماد ومفاتيح الـ webhook وعلامات البطاقات والتسجيل) وكذلك السجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. تُحفظ محاولات الدفع ومعرّفات الدفع دائمًا. وفي OpenCart 4 تُحذف أيضًا أحداث الإضافة وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور الـ webhook وعودة العميل في وضع الصيانة. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.
في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Peach Payments Pay Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.
Peach Payments علامة تجارية مسجّلة لمالكها. وهذه الإضافة غير تابعة لـ Peach Payments ولا تحظى بتأييدها.