VibeFox Helcim for PrestaShop — المساعدة

المتطلبات

PrestaShop: 8.0 إلى 9.x.

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

HTTPS وPCI DSS: تُدخل بيانات البطاقة في صفحة الدفع الخاصة بك، ويرسلها خادمك إلى Helcim عبر HTTPS. لا يتم حفظها أو تسجيلها أبدًا، لكنها تمر عبر خادمك، لذلك يحتاج متجرك إلى شهادة SSL، ويجب أن تلبي استضافتك متطلبات PCI DSS (SAQ D).

حساب Helcim: حساب تاجر لدى Helcim في كندا أو الولايات المتحدة، ورمز API يتمتع بصلاحيات معالجة المعاملات (انظر الإعدادات). تعالج Helcim عملتي CAD وUSD. حساب Helcim للاختبار (المطورين) اختياري لأغراض الاختبار.

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

التثبيت

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

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

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

4. في Helcim، افتح All Tools > Integrations > API Access Configuration، وأنشئ وصولًا إلى API يتمتع بصلاحيات معالجة المعاملات (المشتريات، والتفويضات المسبقة، والتحصيل، والاسترداد)، ثم انسخ رمزه.

5. ألصق الرمز في Live API token، وألصق رمز حساب الاختبار الخاص بك لدى Helcim في Test API token إن كان لديك واحد.

6. اختر Transaction type وAccount currencies، وفعّل Enable / Disable، ثم انقر على Save. للاختبار أولًا، فعّل Test mode وادفع باستخدام حساب الاختبار الخاص بك؛ ثم أوقفه.

عند التثبيت، تنشئ الوحدة حالتين للطلب: Helcim payment authorized وHelcim payment on hold. ويفعّل PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Helcim Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها. وفوق الحقول، تحذرك الصفحة إذا لم تكن العملة الافتراضية لمتجرك ضمن Account currencies، وعندما تكون طريقة الدفع مفعّلة، إذا كان رمز API للوضع الحالي فارغًا. وفي هذه الحالة تُخفى طريقة الدفع في صفحة الدفع.

Helcim

Enable / Disable: Enable Helcim Gateway يفعّل طريقة الدفع أو يوقفها. الافتراضي: off.

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

Description: وصف طريقة الدفع الذي يظهر في صفحة الدفع. الافتراضي: Pay securely with your credit card.

بيانات اعتماد API

في Helcim، انتقل إلى All Tools > Integrations > API Access Configuration، وأنشئ وصولًا إلى API، ثم انسخ رمزه. امنحه صلاحية معالجة المعاملات للمشتريات والتفويضات المسبقة والتحصيل والاسترداد. تستخدم حسابات الاختبار لدى Helcim عنوان API نفسه المستخدم في الحسابات الحية، لذلك يستخدم وضع الاختبار ببساطة رمز حساب الاختبار الخاص بك لدى Helcim.

Live API token: رمز API الخاص بحسابك الحي لدى Helcim. يُستخدم عندما يكون وضع الاختبار متوقفًا.

Test mode: يستخدم Test API token (حساب Helcim للاختبار). تُرسل المدفوعات وعمليات التحصيل والاسترداد إلى حساب الاختبار الخاص بك لدى Helcim، ويرى العملاء إشعار وضع الاختبار. تستخدم عمليات تحصيل الطلب واستردادها دائمًا رمز الوضع الذي تم فيه دفع الطلب. الافتراضي: off.

Test API token: رمز API لحساب Helcim للاختبار (المطورين) الخاص بك. يُستخدم عندما يكون وضع الاختبار مفعّلًا.

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

Clear saved tokens: ضع علامة على رمز وانقر على Save لإزالته. يحافظ الحقل الفارغ على القيمة المحفوظة.

الدفع

Transaction type: طريقة خصم المبلغ من البطاقة.

Account currencies: العملات التي يمكن لحساب Helcim الخاص بك معالجتها. تُخصم الطلبات دائمًا بعملة السلة. تُخفى طريقة الدفع في صفحة الدفع للعملات الأخرى.

متقدم

Debug log: يكتب طلبات API واستجاباتها في logs/wc_hlg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُختصر أرقام البطاقات إلى آخر 4 أرقام. لا يتم تسجيل رمز CVC أو تاريخ الانتهاء أو الرموز أو الأسماء أو العناوين أو رسائل البريد الإلكتروني أو عناوين IP أبدًا. تُسجَّل الأخطاء (المدفوعات المرفوضة أو الفاشلة، وأخطاء API، وعمليات التحصيل والاسترداد الفاشلة) دائمًا، حتى عندما يكون هذا الخيار متوقفًا. الافتراضي: off.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة وملفات السجل. تبقى معاملات Helcim والاستردادات وحالات الطلبات محفوظة دائمًا، لذلك يمكن تحصيل الطلبات المدفوعة سابقًا واستردادها بعد إعادة التثبيت. الافتراضي: off.

صفحة الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا Credit card (Helcim)، مع أيقونة بطاقة)، ويدخل Card Number وExpiry (MM/YY) وCVC وCardholder Name في النموذج الموجود أسفله. وفي وضع الاختبار يعرض النموذج TEST MODE — payments go to a Helcim test account, no real charges are made. عندما يقدّم العميل الطلب، تتحقق الوحدة من المجموع الاختباري لرقم البطاقة، ومن أن تاريخ الانتهاء صالح وليس في الماضي، ومن أن رمز CVC مكوّن من 3 أو 4 أرقام، ومن أن الاسم مُدخل. تظهر الأخطاء في صفحة الدفع، ولا يُرسل شيء إلى Helcim.

ثم يرسل خادمك البطاقة إلى Helcim كشراء أو تفويض مسبق بقيمة إجمالي السلة وبعملة السلة. يُرسل عنوان الفوترة ورقم الهاتف والبريد الإلكتروني للتحقق من العنوان. يظهر الدفع في Helcim برقم فاتورة مكوّن من رقم السلة و-PS ورمز قصير. يرد Helcim ضمن الطلب نفسه. لا يُنشأ الطلب إلا بعد موافقة Helcim على المعاملة، ويصل العميل إلى صفحة تأكيد الطلب القياسية. ولا يوجد أي طلب قبل ذلك.

لا تعمل إلا محاولة دفع واحدة لكل سلة في وقت واحد، ولا يُعاد خصم مبلغ من سلة لديها طلب بالفعل. تستخدم كل محاولة مفتاح idempotency. إذا لم يرد Helcim، فلا يُنشأ أي طلب، وتعيد المحاولة خلال 5 دقائق نتيجة Helcim الأصلية بدلًا من خصم المبلغ من البطاقة مرتين. وإذا تمت الموافقة على الدفع لكن تعذر إنشاء الطلب، فإن المحاولة التالية للسلة نفسها تنشئ الطلب دون خصم البطاقة مرة أخرى.

الرسائل التي قد يراها العميل في صفحة الدفع: Your card was declined. Please check the card details or use another card. عندما يرفض Helcim؛ وPayment failed: مع سبب Helcim للطلبات المرفوضة الأخرى؛ وWe could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. عندما لا يرد Helcim؛ وThis payment method is temporarily unavailable. Please choose another payment method. عندما يكون رمز API مفقودًا أو يرفضه Helcim؛ وYour payment is already being processed. Please wait a moment and check your e-mail before trying again. عند الإرسال المزدوج؛ وYour payment was received, but the order could not be completed automatically. Please contact us — do not pay again. عندما تتم الموافقة على الدفع لكن تعذر إكمال الطلب تلقائيًا. تبقى السلة محفوظة. وتُكتب التفاصيل الفنية في السجل.

لا تستخدم الوحدة HelcimPay.js أو Helcim.js، لذلك تمر بيانات البطاقة عبر خادمك. لا تتضمن الوحدة بطاقات محفوظة، أو اشتراكات، أو مدفوعات ACH أو مصرفية، أو Apple Pay، أو Google Pay، أو 3-D Secure، ولا تتضمن webhooks من Helcim.

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

حالات الطلب

No order: رُفضت البطاقة، أو لم يرد Helcim، أو لم يدفع العميل بعد. لا يوجد إلا السلة. تُكتب حالات الرفض والأخطاء في السجل.

Payment accepted: تمت الموافقة على عملية شراء، أو تم تحصيل تفويض مسبق. يُسجَّل الدفع بمعرّف معاملة Helcim، وتعرض ملاحظة معرّف المعاملة وكود الموافقة ونوع البطاقة وآخر 4 أرقام والوضع.

Helcim payment authorized: تمت الموافقة على تفويض مسبق. الأموال محجوزة فقط. حصّلها أو حرّرها باسترداد كامل.

Helcim payment on hold: وافق Helcim على معاملة، لكن المبلغ أو العملة أو معرّف المعاملة في رده لا يتطابق مع السلة، مثلًا بعد موافقة جزئية أو عند تغيير السلة أثناء الدفع. تقول الملاحظة Helcim response verification FAILED. في حالة الشراء، يُسجَّل الدفع بالمبلغ الذي خصمه Helcim فعليًا. تحقق من المعاملة في Helcim قبل تنفيذ الطلب.

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

Canceled: تم تحرير تفويض مسبق لم يُحصَّل. لم يُخصم أي مبلغ من العميل.

إذا تمت الموافقة على معاملة ثانية لسلة لديها طلب بالفعل، فلن يتغير الطلب. تطلب منك ملاحظة التحقق منها وعكسها أو استردادها في Helcim.

كتلة الدفع في Helcim

تعرض صفحة الطلب كتلة Helcim payment تتضمن معرّف المعاملة (ومعرّف التفويض المسبق بعد التحصيل)، ونوع المعاملة وحالة التحصيل، ورقم الفاتورة، والبطاقة وكود الموافقة، والمبلغ المعتمد، وإجمالي الطلب والمبلغ المسترد، وشارة Test mode للمدفوعات التجريبية، وسجل الاستردادات، وHelcim notes الخاصة بالطلب. يتطلب التحصيل والاسترداد صلاحية تعديل الطلبات.

التحصيل

بالنسبة إلى طلب في حالة Helcim payment authorized، انقر على Capture payment في الكتلة، وأكّد Capture the pre-authorized amount through Helcim? يُحصَّل إجمالي الطلب الحالي مطروحًا منه الاستردادات. قد يكون أقل من المبلغ المفوَّض مسبقًا، لكن لا يمكن أن يكون أعلى منه. يستخدم التحصيل رمز الوضع الذي تم فيه دفع الطلب. بعد نجاح التحصيل يتحول الطلب إلى حالة تم قبول الدفع، ويُسجَّل الدفع بمعرّف معاملة التحصيل. وإذا فشل التحصيل، تعرض الكتلة السبب وتضيفه إلى الملاحظات.

الاسترداد

في الكتلة، أدخل المبلغ (يُملأ تلقائيًا المبلغ الذي لم يُسترد بعد)، واكتب سببًا إن أردت، ثم انقر على Refund via Helcim. أكّد Refund this amount through Helcim? This cannot be undone. الاستردادات الكاملة والجزئية للشراء أو للتفويض المسبق المحصَّل مدعومة، حتى المبلغ الذي خصمه Helcim فعليًا؛ لذلك بعد موافقة جزئية لا يمكنك استرداد أكثر مما دفعه العميل. أما بالنسبة إلى تفويض مسبق لم يُحصَّل، فيكون الزر Release pre-authorization: لا يمكن تحرير إلا المبلغ الكامل، ويُزال الحجز، ويتحول الطلب إلى حالة ملغى.

يُرسل الاسترداد في الوضع الذي تم فيه دفع الطلب، لذلك يجب تعيين رمز ذلك الوضع. ولا يُحتسب الاسترداد إلا إذا وافق عليه Helcim. وإذا رفضه Helcim، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع معرّف معاملة الاسترداد لدى Helcim. يضع الاسترداد الكامل الطلب في حالة Refunded. ولا يغيّر الاسترداد الجزئي الحالة. ولا تؤدي إعادة المحاولة بعد انقضاء المهلة إلى استرداد مزدوج.

لا تنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر Helcim. لا تستقبل الوحدة webhooks من Helcim: عمليات التحصيل والاسترداد والإلغاء التي تتم في لوحة تحكم Helcim لا تنعكس في PrestaShop، لذلك نفّذها من صفحة الطلب.

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

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

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

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

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

لا يظهر Helcim في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي لديه رمز API الخاص به (Live API token، أو Test API token في وضع الاختبار)، وأن عملة السلة ضمن Account currencies. تعرض صفحة الإعدادات تحذيرًا عندما يكون الرمز مفقودًا أو عملة المتجر غير مسموح بها. وفي Payment > Preferences، تحقق من أن الوحدة مسموح بها لعملة السلة، ولدولة العميل، ولمجموعة العميل.

رأى العميل الرسالة «We could not confirm your payment»: لم يرد Helcim، لذلك ربما خُصمت البطاقة. انظر إلى حقل Log: يذكر الخطأ السلة وفاتورة Helcim. تحقق من تلك الفاتورة في Helcim قبل محاولة خصم المبلغ من العميل مرة أخرى. تعيد المحاولة خلال 5 دقائق النتيجة الأصلية ولا تخصم مرتين.

يرى العملاء الرسالة «This payment method is temporarily unavailable»: رمز API للوضع الحالي فارغ أو رفضه Helcim. يطلب السجل التحقق من الرمز وصلاحياته. تأكد من أن وصول API لديه صلاحية معالجة المعاملات.

فشل الدفع لسبب من Helcim: رفض Helcim الطلب، مثلًا بسبب البطاقة أو بيانات الفوترة. تفاصيل ذلك موجودة في السجل.

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

الطلب في حالة Helcim payment on hold: اقرأ الملاحظات في كتلة Helcim. لم يتطابق رد Helcim مع السلة (فشل التحقق من الرد). تحقق من المعاملة في Helcim، ثم نفّذ الطلب أو استرد الدفع.

التحصيل غير ممكن: يجب أن يكون المبلغ المراد تحصيله أكبر من 0 وألّا يتجاوز المبلغ المفوَّض مسبقًا، ويجب تعيين رمز الوضع الذي تم فيه دفع الطلب.

فشل الاسترداد: اقرأ الرسالة. لا يمكن تحرير التفويض المسبق غير المحصَّل إلا بالكامل. تعني الرسالة المتعلقة بالوضع أن رمز الوضع الذي تم فيه دفع الطلب فارغ. ولا يُسجَّل الاسترداد المرفوض.

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

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

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

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