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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبتة ومفعلة. لا يمكن تفعيل الإضافة بدون WooCommerce.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة وانقر Install Now. يمكنك أيضًا رفع مجلد wcp_helcim_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

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

4. افتح الإعدادات: WooCommerce > Settings > Payments > Helcim > Manage، أو انقر Settings أسفل اسم الإضافة في صفحة الإضافات.

5. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، وانقر Activate.

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

7. اختر Transaction type وAccount currencies، ثم فعّل Enable / Disable واحفظ التغييرات. للاختبار أولًا، فعّل Test mode وادفع باستخدام حساب الاختبار الخاص بك؛ ثم أوقف تفعيله بعد ذلك.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Helcim. أعلى الحقول، تحذرك الصفحة إذا لم تكن عملة المتجر إحدى Account currencies، وأيضًا أثناء تفعيل بوابة الدفع إذا كان رمز API للوضع الحالي فارغًا. وفي كلتا الحالتين، يتم إخفاء بوابة الدفع في صفحة الدفع. وفي قائمة طرق الدفع، يتم تمييز بوابة الدفع بأنها بحاجة إلى إعداد حتى يتوفر رمز للوضع الحالي.

Enable / Disable: يؤدي خيار Enable Helcim Gateway إلى تشغيل طريقة الدفع أو إيقافها. الافتراضي: معطل.

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: Use the Test API token (Helcim test account). تذهب المدفوعات والتحصيلات والاستردادات إلى حساب الاختبار الخاص بك في Helcim، ويرى العملاء إشعار وضع الاختبار. وتستخدم الاستردادات والتحصيلات للطلب دائمًا رمز الوضع الذي تم دفع الطلب فيه. الافتراضي: معطل.

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

الدفع

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

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

متقدم

Debug log: خيار Log API requests and responses يسجل في WooCommerce > Status > Logs، والمصدر wcp_helcim_gateway. يتم اختصار أرقام البطاقات إلى آخر 4 أرقام. ولا يتم إطلاقًا تسجيل رموز CVC، أو تاريخ انتهاء الصلاحية، أو الرموز، أو الأسماء، أو العناوين، أو رسائل البريد الإلكتروني، أو عناوين IP. الافتراضي: معطل.

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. الافتراضي: معطل.

صفحة الدفع

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

عند تقديم الطلب، يرسل خادمك بيانات البطاقة إلى Helcim كعملية شراء أو تفويض مسبق لإجمالي الطلب بعملة الطلب. ويتم إرسال عنوان الفاتورة، ورقم الهاتف، والبريد الإلكتروني للتحقق من العنوان. ويظهر الدفع في Helcim برقم فاتورة يتكون من رقم الطلب ورمز قصير. وتجيب Helcim ضمن طلب API نفسه. ولا يتم تعليم الطلب كمدفوع إلا بعد موافقة 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 أو رفضه؛ وYour payment is already being processed. Please wait a moment and check your e-mail before trying again. عند تكرار الإرسال. ويتم تسجيل التفاصيل الفنية في ملاحظات الطلب وسجل الأحداث.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة الدفع (بنفس حقول البطاقة)، وفي صفحة Pay for order. وهي متوافقة مع التخزين عالي الأداء للطلبات في WooCommerce (HPOS).

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

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

حالات الطلب

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

Processing: تمت الموافقة على عملية شراء، أو تم تحصيل تفويض مسبق. وتتحول الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى حالة «مكتمل»، وهو السلوك الافتراضي في WooCommerce. وتعرض ملاحظة الطلب معرّف المعاملة، ورمز الموافقة، ونوع البطاقة، وآخر 4 أرقام، والوضع. ومعرّف المعاملة هو معرّف معاملة Helcim.

On hold (pre-authorization): الأموال محجوزة فقط. قم بتحصيلها باستخدام إجراء الطلب أو قم بإلغاء الحجز عبر استرداد كامل للمبلغ.

On hold after payment: وافقت Helcim على معاملة، ولكن المبلغ أو العملة أو معرّف المعاملة في ردها لا يتطابق مع الطلب. وتنص الملاحظة على Helcim response verification FAILED. تحقق من المعاملة في Helcim قبل تنفيذ الطلب.

التحصيل

افتح الطلب (الحالة «في الانتظار»)، واختر إجراء الطلب Capture Helcim pre-authorization وانقر Update. يتم تحصيل إجمالي الطلب الحالي، مطروحًا منه مبالغ الاسترداد. وقد يكون أقل من المبلغ المعتمد، ولكن ليس أكثر منه. ويستخدم التحصيل رمز الوضع الذي تم دفع الطلب فيه. وبعد التحصيل الناجح، يتحول الطلب إلى حالة «قيد التنفيذ»، ويتغير معرّف المعاملة إلى معاملة التحصيل. وإذا فشل التحصيل، يتم عرض السبب وإضافته إلى ملاحظات الطلب.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ وانقر Refund via Credit card (Helcim) (يعرض الزر Title الخاص بك). وتُدعم الاستردادات الكاملة والجزئية لعملية شراء أو تفويض مسبق تم تحصيله. أما التفويض المسبق غير المحصل، فيمكن استرداده بالكامل فقط: إذ يتم تحرير حجز الأموال ولا يتم فرض أي رسوم على العميل. ويتم إرسال الاسترداد بالوضع الذي تم دفع الطلب فيه، لذا يجب تعيين رمز ذلك الوضع. ولا يُحتسب إلا عندما توافق عليه Helcim. وإذا رفضته Helcim، تعرض WooCommerce الخطأ ولا يتم تسجيل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف معاملة استرداد Helcim. ولا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى استرداد المبلغ مرتين.

لا تتلقى الإضافة webhooks من Helcim. ولا تنعكس عمليات التحصيل والاسترداد والإلغاء التي تتم في لوحة تحكم Helcim داخل WooCommerce، لذا يجب إجراؤها من داخل WooCommerce.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. توجد كتلة الترخيص أعلى صفحة WooCommerce > Settings > Payments > Helcim. الصق المفتاح في License key وانقر Activate. تعرض الكتلة الحالة، على سبيل المثال تاريخ سريان الترخيص ونطاقك. استخدم Check now للتحقق من الحالة مرة أخرى، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك على vibefox.net.

يعمل مفتاح واحد على نطاق واحد. وإزالة المفتاح من موقع ما لا تؤدي إلى تحرير فتحة النطاق الخاصة به. حرر الفتحة من خلال حسابك على vibefox.net.

بدون مفتاح نشط، لا تظهر Helcim للعملاء في صفحة الدفع. وإذا بدأ الدفع على أي حال، يرى العميل This payment method is not available. Please choose another one. ويستمر مديرو المتاجر الذين قاموا بتسجيل الدخول في رؤية طريقة الدفع، مميزة بعلامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة وتجربتها قبل شراء مفتاح. ويظهر تذكير في صفحة الإضافات وعلى صفحات WooCommerce. ولا تتأثر الطلبات الحالية: إذ تظل عمليات التحصيل والاسترداد تعمل كالمعتاد.

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

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

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

لم تجب Helcim ويظل الطلب في حالة «بانتظار الدفع»: قد يكون قد تم خصم المبلغ من البطاقة. اقرأ ملاحظة الطلب وتحقق من الفاتورة في Helcim قبل خصم المبلغ من العميل مرة أخرى. وتؤدي إعادة المحاولة في غضون 5 دقائق إلى إرجاع النتيجة الأصلية ولا تخصم المبلغ مرتين.

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

فشل الدفع مع سبب من Helcim: رفضت Helcim الطلب، على سبيل المثال بسبب البطاقة أو تفاصيل الفاتورة. وتتضمن ملاحظة الطلب التفاصيل.

الطلب في حالة «في الانتظار» بعد الدفع: اقرأ ملاحظة الطلب. إما أن الطلب قد تم تفويضه مسبقًا وينتظر التحصيل، أو أن رد Helcim لم يتطابق مع الطلب (فشل التحقق من صحة الاستجابة).

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

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

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

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

للمطورين: يُعدل الفلتر wc_hlg_supported_currencies قائمة العملات، ويُعدل wc_hlg_card_brands أيقونات البطاقات في صفحة الدفع.

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

عند إلغاء تفعيل الإضافة تُحفظ جميع البيانات. للإزالة، ألغِ التفعيل ثم احذفها من صفحة Plugins. ويتم دائمًا حذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة. ولا تُحذف إعدادات بوابة الدفع وخيارات الإضافة الخاصة وملفات السجلات إلا إذا كان خيار Delete data on uninstall مفعّلًا. وخلاف ذلك، فإنها تظل موجودة لإعادة التثبيت لاحقًا. وتُعد بيانات الطلبات جزءًا من سجل الطلبات ولا تُحذف أبدًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات الخاصة بها.

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