VibeFox Pin Payments for OpenCart — المساعدة

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

حساب Pin Payments: حساب تاجر لدى Pin Payments (للشركات في أستراليا أو نيوزيلندا؛ يمكن للعملاء الدفع من أي مكان). تحتاج إلى المفتاح القابل للنشر (publishable key) والمفتاح السري (secret key) الخاصين به، للإنتاج، ولبيئة الاختبار عند إجراء الاختبارات. لا يلزم سرّ webhook: فالإضافة لا تستخدم webhooks. تُرسل بيانات البطاقة من متصفح العميل مباشرةً إلى Pin Payments عبر Pin.js، ولا تصل إلى متجرك أبدًا، لذلك يندرج المتجر ضمن PCI SAQ A-EP.

العملة: AUD أو USD أو NZD أو SGD أو EUR أو GBP أو CAD أو HKD أو JPY أو MYR أو THB أو PHP أو ZAR أو IDR. يُخصم الطلب بعملته الخاصة.

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

التثبيت

يحتوي التنزيل على ملف zip واحد يضم الحزم الخاصة بإصداري OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_pinpayments_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_pinpayments_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_pinpayments_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذا لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت، يمكنك نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Pin Payments Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

4. في لوحة Pin Payments، افتح Account > API Keys وانسخ مفاتيح الاختبار الخاصة بك إلى Test publishable key وTest secret key. أبقِ Test mode مفعّلًا، وفعّل Enable/Disable، وانقر على Save.

5. أجرِ طلبًا تجريبيًا ببطاقة اختبار من Pin Payments. عندما تعمل كل الأمور بشكل صحيح، أدخل مفاتيح الإنتاج، وأوقف Test mode، ثم احفظ.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_pinpayments_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة بعد إعادة تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Pin Payments Gateway، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح Pin Payments كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit. تُدرج الأقسام على اليسار، وزر Save أسفل القائمة يحفظ الصفحة كاملةً. وتعرض الصفحة فوق الإعدادات Pin Payments is in TEST MODE: the test API and test keys are used, no real charges are made. ما دام وضع الاختبار مفعّلًا؛ وخطأً ما دام المفتاح القابل للنشر أو المفتاح السري للوضع الحالي فارغًا (فتُخفى طريقة الدفع عندئذٍ في صفحة الدفع)؛ وخطأً عندما لا يدعم Pin Payments العملة الافتراضية للمتجر (مع قائمة العملات المدعومة). ومن دون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، إذا كان أي حقل غير صحيح فلن يُحفظ شيء: لا يمكن أن يكون Title فارغًا (أدخل عنوانًا لطريقة الدفع (بحد أقصى 128 حرفًا).)، ويجب أن يكون Sort Order عددًا صحيحًا (القيم السالبة مسموحة)، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن يكون Geo Zone وحالات الطلب موجودة.

Pin Payments

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع، وهو أيضًا الاسم المحفوظ في الطلب. الافتراضي: Credit card (Pin Payments). حقل مطلوب، بحد أقصى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق نموذج البطاقة. الافتراضي: Pay with your credit card via Pin Payments.

Sort Order: موقع Pin Payments بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض نموذج البطاقة فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي سلة الشراء، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب حتى تُعرض طريقة الدفع. اتركه فارغًا لعرضها مهما كان المبلغ.

مفاتيح API

تجد مفاتيحك في لوحة Pin Payments (تتضمن الصفحة رابطًا إلى dashboard.pinpayments.com) ضمن Account > API Keys. تعمل مفاتيح الاختبار مع واجهة الاختبار البرمجية فقط، وتعمل مفاتيح الإنتاج مع الواجهة البرمجية للإنتاج فقط. يستخدم Pin.js المفتاح القابل للنشر في متصفح العميل. ولا يغادر المفتاح السري خادمك أبدًا.

Test mode: يستخدم بيئة الاختبار الخاصة بـ Pin Payments (test-api.pinpayments.com) ومفاتيح الاختبار. لا تُجرى أي عمليات خصم حقيقية، ويرى العملاء وضع الاختبار — لن تُجرى أي عمليات خصم حقيقية. فوق نموذج البطاقة. وعند إيقافه تُستخدم الواجهة البرمجية للإنتاج ومفاتيح الإنتاج. تستخدم عمليات استرداد الطلب دائمًا مفاتيح البيئة التي دُفع فيها الطلب. الافتراضي: مفعّل.

Test publishable key: المفتاح القابل للنشر لحساب الاختبار الخاص بك في Pin Payments.

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

Live publishable key: المفتاح القابل للنشر لحساب الإنتاج الخاص بك في Pin Payments.

Live secret key: المفتاح السري لحساب الإنتاج الخاص بك في Pin Payments.

تُزال المسافات حول المفاتيح. لا تُعرض المفاتيح السرية المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للاحتفاظ به. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح سري محفوظ، ضع علامة على Clear the saved value on save أسفل الحقل ثم انقر على Save.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن يرد Pin Payments على عملية الخصم. يعرض كل حقل أدناه حالات طلبات OpenCart لديك.

Order Status After Payment: خُصمت البطاقة بالمبلغ والعملة المطابقين تمامًا للطلب. الافتراضي: Processing.

On Hold (Review) Status: المبلغ أو العملة المخصومان يختلفان عن الطلب، أو الخصم مُعتمد لكنه غير محصَّل، أو لم يقدم Pin Payments ردًا واضحًا (انتهت المهلة، أو حدث خطأ في الخادم)، لذا قد يكون الخصم موجودًا. تخبرك ملاحظة بما يجب التحقق منه في لوحة Pin Payments. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Refunded Status: تُعيَّن بعد استرداد الدفعة بالكامل من تبويب الطلب. الافتراضي: Refunded.

متقدم

Debug log: يكتب استدعاءات واجهة Pin Payments البرمجية إلى الملف wc_ppg_debug.log.php في مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى wc_ppg_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا؛ فعّل هذا الخيار لتسجيل كل استدعاء API أيضًا. لا تُسجَّل بيانات البطاقات ولا مفاتيح API ولا البيانات الشخصية للعملاء أبدًا. الافتراضي: معطّل.

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر المفاتيح السرية.

Import: ألصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى المفاتيح السرية المحفوظة كما هي.

صفحة الدفع

تُعرض طريقة الدفع عندما تكون مفعّلة، ويكون المفتاحان لوضع الحالي مُدخلين، وتكون عملة الطلب إحدى العملات الـ 14 المدعومة، ويقع عنوان الدفع ضمن Geo Zone المحددة، ويبلغ الطلب Total.

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit card (Pin Payments)). ينشئ OpenCart الطلب في خطوة Confirm Order، ولا يزال بلا حالة. وهناك يرى العميل وصفك، وأيقونات Visa وMastercard وAmerican Express، ونموذج البطاقة: Card number وExpiry (MM / YY) وCVC وName on card. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في نافذة Payment method options؛ ثم يظهر نموذج البطاقة في كتلة التأكيد أسفل صفحة الدفع، فوق زر Confirm Order. وقبل الإرسال، يتحقق النموذج من طول رقم البطاقة، وشهر الانتهاء وسنته، وCVC مكوَّن من 3 أو 4 أرقام، والاسم.

عندما ينقر العميل على Confirm Order، يرسل Pin.js من المتصفح بيانات البطاقة وعنوان دفع الطلب (في OpenCart 4، عندما لا يطلب الدفع عنوان دفع، فعنوان الشحن) مباشرةً إلى Pin Payments، ويحصل على رمز بطاقة لمرة واحدة. ولا يصل إلى متجرك إلا هذا الرمز. ثم تنشئ الإضافة خصمًا محصَّلًا بإجمالي الطلب وبعملة الطلب، مع البريد الإلكتروني وعنوان IP الخاصين بالعميل، والوصف <store name> - Order <order number>. ويرد Pin Payments في الطلب نفسه.

بعد نجاح الخصم، يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون؛ ويُفرَّغ السلة، ويرى العميل صفحة نجاح الطلب في OpenCart مع العبارة Your card payment has been received. وإذا انتقل الطلب إلى حالة المراجعة، تعرض الصفحة: تم استلام دفعتك بالبطاقة وهي قيد المراجعة. سنحدّث طلبك فور اكتمال المراجعة.

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

لا تعمل إلا محاولة دفع واحدة لكل سلة في الوقت نفسه. يتلقى الإرسال الثاني الرسالة هذا الطلب قيد الدفع بالفعل. يُرجى الانتظار لحظة والتحقق من بريدك الإلكتروني قبل المحاولة مرة أخرى. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويحدّث OpenCart 4 طلب الصفحة (بعد بطاقة مرفوضة يدفع العميل الطلب نفسه)، وتنتقل السلة التي دُفعت بالفعل بطلب آخر مباشرةً إلى صفحة النجاح، وتنقل محاولة سابقة خصمت أموالًا أو ربما خصمتها حالتها إلى الطلب بدلًا من إنشاء خصم جديد. ولا يمكن استخدام رمز البطاقة إلا مرة واحدة: فبعد محاولة فاشلة، أو عندما يغيّر العميل بيانات البطاقة، يُنشأ رمز جديد.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. إذا كان لهذا الطلب حالة بالفعل عندما يؤكد العميل شراءً جديدًا (مثلًا دُفع ولم تُفتح صفحة النجاح أبدًا، أو ألغيته)، يعود العميل إلى صفحة الدفع، ويصبح Confirm Order التالي دفعًا لطلب جديد من السلة الحالية. وفوق صفحة الدفع يرى العميل Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. عندما أُغلق الطلب، أو Your previous order #(الرقم) has already been placed. Your cart has changed: please confirm the new order to pay for it. عندما سُجّل لسلة سابقة. ولا يُعرض طلب مدفوع أبدًا على أنه مدفوع لسلة مختلفة.

عندما يفشل الدفع، يبقى الطلب بلا حالة. ويبقى العميل في خطوة Confirm Order، وتُحفظ السلة، ويظهر فوق نموذج البطاقة واحدة من هذه الرسائل: تم رفض بطاقتك. يُرجى استخدام بطاقة أخرى أو الاتصال بالبنك الخاص بك.؛ رصيد بطاقتك غير كافٍ. يُرجى استخدام بطاقة أخرى.؛ انتهت صلاحية بطاقتك. يُرجى استخدام بطاقة أخرى.؛ رمز الأمان للبطاقة (CVC) غير صحيح.؛ نوع البطاقة هذا غير مقبول. يُرجى استخدام Visa أو Mastercard أو American Express.؛ فشل الدفع: مع سبب Pin Payments للبيانات المرفوضة؛ انتهت صلاحية بيانات بطاقتك. يُرجى إدخالها مجددًا والمحاولة مرة أخرى. عندما لا يمكن استخدام الرمز؛ تعذّر تحميل نموذج البطاقة الآمن. يُرجى إعادة تحميل الصفحة أو اختيار طريقة دفع أخرى. عندما لا يُحمَّل Pin.js؛ مدفوعات البطاقات غير متاحة مؤقتًا. يُرجى المحاولة لاحقًا أو اختيار طريقة دفع أخرى. عندما يرفض Pin Payments المفتاح السري؛ تعذّرت معالجة دفعتك. يُرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. للأخطاء الأخرى. ويُكتب السبب التقني في السجل.

لا تتضمن الإضافة تدفق 3-D Secure. وإذا كان حساب Pin Payments يتطلب 3-D Secure، يبقى الخصم معلّقًا، ولا يحصل الطلب على أي حالة، ويرى العميل تعذّر إتمام دفعتك بالبطاقة (مطلوب تحقق إضافي). يُرجى تجربة بطاقة أخرى أو طريقة دفع أخرى. ولا يوجد وضع التفويض فقط مع التحصيل لاحقًا، ولا بطاقات محفوظة، ولا اشتراكات، ولا Apple Pay أو Google Pay، ولا webhooks.

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

حالات الطلب

بلا حالة (طلب مفقود): رُفضت البطاقة، أو كان الخصم يتطلب 3-D Secure، أو لم يدفع العميل. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Order Status After Payment (الافتراضي Processing): أبلغ Pin Payments عن خصم ناجح ومحصَّل بالمبلغ والعملة المطابقين تمامًا للطلب. تعرض ملاحظة المبلغ ورمز الخصم (وعبارة TEST MODE للدفعات التجريبية).

On Hold (Review) Status (الافتراضي Pending): يحتاج الخصم إلى مراجعتك. توضح الملاحظة السبب: خصم Pin Payments مبلغًا أو عملة تختلف عن الطلب، أو الخصم مُعتمد لكنه غير محصَّل (حصّله في لوحة Pin Payments ثم غيّر حالة الطلب)، أو لم يقدم Pin Payments ردًا واضحًا (ابحث عن وصف الخصم في لوحة Pin Payments قبل شحن الطلب).

Refunded Status (الافتراضي Refunded): استُرد الخصم بالكامل عبر الإضافة.

إذا أُجري خصم ثانٍ لسلة دُفعت بالفعل، فلا يتغير الطلب المدفوع. وتطلب ملاحظة منك التحقق منه واستراده في لوحة Pin Payments.

الملاحظات هي إدخالات في History الخاص بالطلب، ولا يراها العميل.

VibeFox Pin Payments Gateway tab

في Sales > Orders افتح طلبًا دُفع عبر Pin Payments. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Pin Payments Gateway رمز Charge مع الوسم Test للدفعات التجريبية، وStatus، وعلامة Card وأرقامها الأربعة الأخيرة، والمبالغ Charged / order / refunded، وCharge description، ونموذج الاسترداد، وسجل الاستردادات، وPin Payments notes الخاصة بالطلب. وتظهر علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في علامة التبويب VibeFox Pin Payments Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واختياريًا Reason (optional)، ثم انقر على Refund via Pin Payments. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Pin Payments؟ لا يمكن التراجع عن هذا الإجراء. تُدعم الاستردادات الكاملة والجزئية. ويلزمك صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). تقتصر الاستردادات على المبلغ والعملة اللذين خصمهما Pin Payments فعليًا، لذلك بعد اختلاف في المبلغ أو العملة يمكنك الاسترداد حتى مقدار ما دفعه العميل، لا إجمالي الطلب. يُرسل الاسترداد إلى البيئة (الاختبار أو الإنتاج) التي دُفع فيها الطلب، لذلك يجب أن يكون المفتاح السري لذلك الوضع مُعيّنًا. ويعالج Pin Payments الاستردادات بشكل غير متزامن، لذلك تكون الحالة عادةً Pending. ويُضاف الطلب الناجح إلى سجل الاستردادات والملاحظات مع رمز الاسترداد من Pin Payments وحالته. ويعيّن الاسترداد الكامل الطلب إلى Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، مثل تغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. وإذا رفض Pin Payments الاسترداد أو لم يرد، تعرض علامة التبويب الخطأ ولا يُسجَّل أي استرداد.

عندما لا يكون هناك خصم مسجَّل للطلب (لم يقدم Pin Payments ردًا واضحًا)، لا تعرض علامة التبويب نموذج الاسترداد، وتخبرك بالوصف الذي يجب البحث عنه في لوحة Pin Payments.

لا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر Pin Payments. ولا تتم مزامنة الاستردادات التي تُجرى في لوحة Pin Payments مع OpenCart، لذا أجرِها من صفحة الطلب.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Pin Payments Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit، فوق الإعدادات. ألصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموَّهًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-payment-pinpayments والرابط 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.

من دون مفتاح نشط، لا تظهر Pin Payments للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل الرسالة This payment method is not available. Please choose another one. أما مستخدم الإدارة الذي سجّل الدخول إلى لوحة الإدارة في المتصفح نفسه فلا يزال يرى طريقة الدفع في المتجر، مع الوسم (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. في OpenCart 4 لا تتوفر هذه المعاينة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تُخفى طريقة الدفع عن الجميع من دون مفتاح نشط. وبعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. ولا تتأثر الطلبات الحالية: تعمل استردادات الطلبات المدفوعة سابقًا كما هي.

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

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

لا تظهر Pin Payments في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاحين الخاصين بالوضع الحالي مُدخلان (Test publishable key وTest secret key في وضع الاختبار، وإلا فالمفاتيح الفعلية)، وأن عملة الطلب إحدى العملات الـ 14 المدعومة. وتحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المحدد في الإعدادات. وتعرض صفحة الإعدادات خطأً عند غياب المفاتيح، وعند عدم دعم عملة المتجر.

تمت الدفعة لكن الطلب في حالة المراجعة: اقرأ الملاحظات في علامة التبويب VibeFox Pin Payments Gateway (انظر حالات الطلب). وإذا لم يقدم Pin Payments ردًا واضحًا، فابحث في لوحة Pin Payments عن خصم بالوصف <store name> - Order <order number>، ثم أنجز الطلب أو استرد الخصم من اللوحة.

يرى العميل الرسالة «Your payment was received, but the order could not be completed automatically»: خُصمت البطاقة، لكن تعذّر تعيين حالة الطلب (مثلًا لأن الطلب حُذف في الأثناء). والسبب مدوَّن في السجل. ويُطلب من العميل ألا يدفع مرة أخرى؛ وإعادة إرسال السلة نفسها تمنح الطلب حالته دون خصم جديد.

يرى العميل الرسالة «This payment method is not available. Please reload the checkout page.»: لم تعد جلسة الدفع تطابق الطلب، أو أُوقفت طريقة الدفع في الأثناء. يعيد العميل تحميل صفحة الدفع.

يرى العملاء الرسالة «Card payments are temporarily unavailable»: رفض Pin Payments المفتاح السري، أو المفتاح الخاص بالوضع الحالي مفقود. تعمل مفاتيح الاختبار في وضع الاختبار فقط، وتعمل المفاتيح الفعلية في وضع الإنتاج فقط. ويعرض السجل السبب.

تفشل الطلبات برسالة «additional verification is required»: يتطلب حساب Pin Payments الخاص بك تفعيل 3-D Secure، وهو غير مدعوم في الإضافة. اطلب من Pin Payments إيقاف إلزامية 3-D Secure.

تعذّر تحميل نموذج البطاقة الآمن: لم يُحمَّل Pin.js من شبكة CDN الخاصة بـ Pin Payments في المتصفح، ربما بسبب أداة حجب للنصوص البرمجية، أو إضافة متصفح تدمج النصوص البرمجية أو تعدّلها. استثنِ صفحة الدفع من مثل هذه التحسينات.

لم يستجب Pin Payments: لم يُنشأ رمز البطاقة في المتصفح خلال 30 ثانية. يمكن للعميل التحقق من الاتصال والمحاولة مرة أخرى؛ ولم يُخصم أي مبلغ.

فشلت الدفعة لسبب من Pin Payments: رفض Pin Payments تفاصيل الخصم، مثل مبلغ أقل من الحد الأدنى للخصم في العملة. يرى العميل السبب، ويحتوي السجل على رمز الخطأ.

يفشل الاسترداد: اقرأ الرسالة في علامة التبويب. تعني الرسالة المتعلقة بالوضع TEST أو LIVE أن المفتاح السري للوضع الذي دُفع فيه الطلب فارغ. وتعني Pin Payments did not confirm the refund أنه لم يصل أي رد؛ تحقّق من الخصم في لوحة Pin Payments قبل المحاولة مرة أخرى. وتشير at most إلى المبلغ الذي ما زال قابلًا للاسترداد من الخصم.

الدفعات التجريبية: يستخدم وضع الاختبار بيئة الاختبار ومفاتيحه. استخدم بطاقات الاختبار من وثائق المطورين الخاصة بـ Pin Payments، مثل 4200 0000 0000 0000 (ناجحة)، مع أي تاريخ انتهاء مستقبلي وأي CVC. تحتفظ الطلبات بالوضع الذي دُفعت فيه، لذلك تذهب الاستردادات إلى البيئة الصحيحة حتى بعد تبديل الوضع.

مكان العثور على الأخطاء: تُكتب الأخطاء دائمًا في السجل؛ راجع حقل Log في صفحة الإضافة. فعّل Debug log لرؤية كل استدعاء API.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، وانقر على Uninstall (الزر الأحمر −) بجوار VibeFox Pin Payments Gateway. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. ويحذف OpenCart إعدادات الإضافة الخاصة به دائمًا: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلب في قسم الطلبات، وتعود إلى قيمها الافتراضية عند إعادة التثبيت. ويُحذف أيضًا حدث OpenCart الخاص بالإضافة (في OpenCart 4 حدثاها، اللذان يعرضان الرسائل في صفحة النجاح وفوق صفحة الدفع). وإذا كان Delete data on uninstall مفعّلًا، تُحذف إعدادات البوابة الأخرى (العنوان والوصف ووضع الاختبار والمفاتيح ومفتاح سجل التصحيح) والسجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. وتُحفظ خصومات Pin Payments واستردادها دائمًا، لذا يمكن استرداد الطلبات المدفوعة سابقًا حتى بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Pin Payments Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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