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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

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

التثبيت

1. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Pin Payments Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالة الطلب Pin Payments payment on hold. وتعرض PrestaShop وحدة دفع جديدة للعملات ومجموعات العملاء والدول النشطة وقت التثبيت. يمكنك تغيير ذلك في Payment > Preferences؛ ويجب تحديد الدول التي تفعّلها لاحقًا هناك.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وتعرض الصفحة فوق الحقول تحذيرًا أثناء تفعيل وضع الاختبار، وخطأً إذا كان المفتاح القابل للنشر أو المفتاح السري للوضع الحالي فارغًا، وخطأً إذا كانت Pin Payments لا تدعم عملة المتجر الافتراضية (مع قائمة العملات المدعومة). ومن دون المفتاحين للوضع الحالي تُخفى طريقة الدفع في صفحة الدفع. ولا يُحفظ حقل Title الفارغ: فتعرض الصفحة Enter a title for the payment method.

Pin Payments

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

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

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay with your credit card via Pin Payments.

مفاتيح API

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

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

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

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

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

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

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

Clear saved secrets: حدد مفتاحًا سريًا وانقر على Save لإزالته. ويُبقي الحقل الفارغ القيمة المحفوظة.

متقدم

Debug log: يكتب في logs/wc_ppg_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. وتُسجَّل الأخطاء دائمًا؛ فعّل هذا الخيار لتسجيل كل استدعاء API أيضًا. ولا تُسجَّل بيانات البطاقات ومفاتيح API والبيانات الشخصية للعملاء أبدًا. الافتراضي: معطّل.

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

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

صفحة الدفع

تظهر طريقة الدفع عندما تكون مفعّلة، ويكون المفتاحان للوضع الحالي مُعبَّأين، وتكون عملة السلة واحدة من العملات الـ14 المدعومة (AUD وUSD وNZD وSGD وEUR وGBP وCAD وHKD وJPY وMYR وTHB وPHP وZAR وIDR)، ويكون مسموحًا للوحدة بالعمل مع السلة في Payment > Preferences.

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit card (Pin Payments)، مع أيقونات Visa وMastercard وAmerican Express) ويملأ Card number وExpiry (MM / YY) وCVC وName on card. وقبل الإرسال يتحقق النموذج من طول رقم البطاقة، وشهر الانتهاء وسنته، ورمز CVC المكوّن من 3 أو 4 أرقام، والاسم.

عندما يُقدِّم العميل الطلب، يرسل Pin.js بيانات البطاقة وعنوان الفوترة للسلة من المتصفح مباشرةً إلى Pin Payments ويحصل على رمز بطاقة لمرة واحدة. ولا يُرسَل إلى متجرك سوى هذا الرمز. ثم تُنشئ الوحدة خصمًا مُحصَّلًا بمجموع السلة بعملة السلة، مع بريد العميل الإلكتروني والوصف <shop name> - Cart <cart number>. ويرد Pin Payments في الطلب نفسه. ولا يوجد أي طلب قبل هذا الرد.

بعد خصم ناجح يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب المعتادة مع العبارة Your card payment has been received. وإذا انتقل الطلب إلى Pin Payments payment on hold، تعرض الصفحة Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

إذا لم ترد Pin Payments (انتهاء المهلة، خطأ في الخادم، رد غير قابل للقراءة)، فقد يكون الخصم قد أُنشئ مع ذلك. ويُنشأ الطلب عندئذٍ في Pin Payments payment on hold دون دفع، وتعرض صفحة التأكيد We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. ولا يُنشئ إرسال السلة نفسها مرة أخرى خصمًا ثانيًا أبدًا.

لا تعمل إلا محاولة دفع واحدة لكل سلة في وقت واحد. ويتلقى الإرسال الثاني This order is already being paid. Please wait a moment and check your e-mail before trying again. ولا يُعاد خصم سلة لديها طلب بالفعل، أو محاولة سابقة خصمت المال أو ربما خصمته؛ بل يُنشأ الطلب من تلك المحاولة. ولا يمكن استخدام رمز البطاقة إلا مرة واحدة: فبعد محاولة فاشلة، أو عندما يغيّر العميل بيانات البطاقة، يُنشأ رمز جديد.

عند فشل الدفع لا يُنشأ أي طلب. يبقى العميل في خطوة الدفع، وتُحفظ السلة، وتظهر إحدى هذه الرسائل: Your card was declined. Please use another card or contact your bank.؛ Your card has insufficient funds. Please use another card.؛ Your card has expired. Please use another card.؛ The card security code (CVC) is incorrect.؛ This card type is not accepted. Please use Visa, Mastercard or American Express.؛ Payment failed: مع سبب Pin Payments للبيانات المرفوضة؛ Your card details have expired. Please enter them again and retry. عندما لا يمكن استخدام الرمز؛ The secure card form could not be loaded. Please reload the page or choose another payment method. عندما لا يُحمَّل Pin.js؛ Card payments are temporarily unavailable. Please try again later or choose another payment method. عندما ترفض Pin Payments المفتاح السري؛ Your payment could not be processed. Please try again or choose another payment method. للأخطاء الأخرى. ويُكتب السبب التقني في السجل.

لا تتضمن الوحدة مسار 3-D Secure. وإذا كان حساب Pin Payments يتطلب 3-D Secure، يبقى الخصم معلقًا، ولا يُنشأ أي طلب، ويرى العميل Your card payment could not be completed (additional verification is required). Please try another card or another payment method. ولا يوجد وضع التفويض فقط مع تحصيل لاحق، ولا بطاقات محفوظة، ولا اشتراكات، ولا Apple Pay أو Google Pay، ولا webhooks.

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

حالات الطلب

No order yet: رُفضت البطاقة، أو كان الخصم يتطلب 3-D Secure، أو لم يدفع العميل. ولا يوجد سوى السلة.

Payment accepted: أبلغت Pin Payments عن خصم ناجح ومُحصَّل بالمبلغ والعملة الدقيقين لمجموع السلة. ويُسجَّل الدفع برمز خصم Pin Payments بوصفه معرّف المعاملة، وتعرض ملاحظة المبلغ ورمز الخصم (وTEST MODE للمدفوعات التجريبية).

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

Refunded: تم استرداد الخصم بالكامل عبر الوحدة.

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

كتلة Pin Payments

تعرض صفحة الطلب كتلة Pin Payments تتضمن شارة Test mode للمدفوعات التجريبية، ورمز الخصم، والحالة، وعلامة البطاقة وآخر أربعة أرقام، والمبلغ المخصوم، وإجمالي الطلب والمبلغ المسترد، وDescription at Pin Payments، وسجل الاستردادات، وPin Payments notes الخاصة بالطلب.

الاستردادات

في كتلة Pin Payments أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واكتب سببًا إن أردت، ثم انقر على Refund via Pin Payments. أكِّد السؤال Refund this amount through Pin Payments? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. وتحتاج إلى صلاحية تعديل الطلبات. والاستردادات مقيّدة بالمبلغ والعملة اللذين خصمتهما Pin Payments فعليًا؛ لذلك بعد اختلاف في المبلغ أو العملة يمكنك الاسترداد حتى ما دفعه العميل، لا إجمالي الطلب. ويُرسَل الاسترداد إلى البيئة (الاختبار أو الإنتاج) التي دُفع فيها الطلب، لذلك يجب تعيين المفتاح السري لذلك الوضع. وتعالج Pin Payments الاستردادات بشكل غير متزامن، لذلك تكون الحالة عادةً قيد الانتظار. ويُضاف الطلب الناجح إلى سجل الاستردادات والملاحظات مع رمز استرداد Pin Payments وحالته. ويضبط الاسترداد الكامل الطلب على Refunded. ولا يغيّر الاسترداد الجزئي الحالة. وإذا رفضت Pin Payments الاسترداد أو لم ترد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد.

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

لا تنشئ الوحدة إشعارات دائنة (credit slips). ولا تُعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب الأموال عبر Pin Payments. والاستردادات التي تُجرى في لوحة Pin Payments لا تُزامَن مع PrestaShop، لذلك أجرِها من صفحة الطلب.

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

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

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

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

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

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

تم الدفع لكن الطلب في Pin Payments payment on hold: اقرأ الملاحظات في كتلة Pin Payments (انظر حالات الطلب). إذا لم تعطِ Pin Payments ردًا واضحًا، فابحث في لوحة Pin Payments عن خصم بالوصف <shop name> - Cart <cart number>، ثم جهّز الطلب وأرسله أو استرد الخصم من اللوحة.

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

يرى العملاء 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 (تنجح) أو 4100 0000 0000 0001 (تُرفض)، مع أي تاريخ انتهاء مستقبلي وأي رمز CVC. وتحتفظ الطلبات بالوضع الذي دُفعت فيه، لذلك تذهب الاستردادات إلى البيئة الصحيحة بعد تبديل الوضع.

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

الإلغاء

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

Pin Payments علامة تجارية مسجلة لمالكها. هذه الوحدة غير تابعة لـ Pin Payments ولا معتمدة من قِبلها.