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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبت ومفعّل. ترفض الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث.

HTTPS: يجب أن يكون موقعك متاحًا من الإنترنت عبر HTTPS، حتى يتمكن Cardcom من إرسال إشعار الدفع.

العملة: يجب أن تكون عملة الطلب ILS أو USD أو EUR أو GBP. وبأي عملة أخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب Cardcom: للمدفوعات الحقيقية تحتاج إلى حساب تاجر لدى Cardcom مع رقم طرفية واسم مستخدم API وكلمة مرور API. وتحتاج المدفوعات إلى رقم الطرفية واسم مستخدم API فقط، وتُستخدم كلمة مرور API للاستردادات من WooCommerce فقط. ويعمل وضع الاختبار دون حساب Cardcom.

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

التثبيت

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

2. انقر Activate.

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

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

5. فعّل Enable/Disable، واترك Test Mode مفعّلًا، وأجرِ طلبًا تجريبيًا ببطاقة 4580 0000 0000 0000 بأي تاريخ انتهاء مستقبلي وCVV 123.

6. للمدفوعات الحقيقية ألغِ تحديد Test Mode، وأدخل Terminal Number وAPI Username وAPI Password التي حصلت عليها من Cardcom.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Cardcom. تعرض الصفحة فوق الحقول Test mode is on. ما دام وضع الاختبار مفعّلًا. وفي وضع الإنتاج تحذّرك عند نقص رقم الطرفية أو اسم مستخدم API (فتبقى Cardcom مخفية عند الدفع)، وتذكّرك بأنه بدون كلمة مرور API لا يمكن إجراء الاستردادات من WooCommerce. وتحذّرك أيضًا عندما لا تكون عملة المتجر مدعومة. وعند حفظ وضع الإنتاج دون رقم الطرفية أو اسم مستخدم API، تُعرض رسالة خطأ تخبرك بأن البوابة ستبقى مخفية عند الدفع حتى يتم إدخالهما.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Credit Card (Cardcom).

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

وضع الاختبار

يستخدم وضع الاختبار طرفية Cardcom التجريبية العامة 1000 (اسم مستخدم API: CardTest1994). لا يُخصم أي مبلغ حقيقي، ولا يلزم حساب Cardcom. بطاقة الاختبار: 4580 0000 0000 0000، بأي تاريخ انتهاء مستقبلي وCVV 123. وفي وضع الاختبار تعرض صفحة الدفع أيضًا سطرًا يذكر بطاقة الاختبار هذه.

Test Mode: Enable test mode (terminal 1000, no real money). الافتراضي: مفعّل. ألغِ تحديده لقبول مدفوعات حقيقية ببيانات اعتماد الإنتاج أدناه. تُرسل الاستردادات دائمًا ببيانات اعتماد الوضع الذي دُفع فيه الطلب.

بيانات اعتماد الإنتاج

يوفّر Cardcom رقم الطرفية واسم مستخدم API وكلمة مرور API مع حساب التاجر لديك: في لوحة تحكم Cardcom ضمن إعدادات API، أو من دعم Cardcom. تُستخدم هذه الحقول في وضع الإنتاج فقط.

Terminal Number: رقم طرفيتك لدى Cardcom. يجب أن يحتوي على أرقام فقط. وإذا أدخلت غير ذلك تظهر رسالة خطأ ويُحتفظ بالقيمة السابقة.

API Username: اسم مستخدم API (ApiName) لدى Cardcom لهذه الطرفية. تُحذف المسافات عند الحفظ.

API Password: كلمة مرور API لدى Cardcom. تُستخدم فقط للاستردادات من WooCommerce، وتُحفظ كما كتبتها تمامًا.

صفحة الدفع

يرسل Cardcom إشعارات الدفع (IndicatorUrl) إلى العنوان المعروض في هذا القسم. ويبدو بالشكل https://your-site/wc-api/cardcom_p_callback/. يُمرَّر العنوان إلى Cardcom تلقائيًا مع كل دفعة، مع رقم الطلب، فلا يلزم أي إعداد في Cardcom. ويجب أن يكون متاحًا من الإنترنت.

Operation: ما الذي تفعله Cardcom في صفحة الدفع.

Max Installments: الحد الأقصى لعدد الأقساط (الدفعات) التي يمكن للعميل اختيارها في صفحة Cardcom، من 1 إلى 36. الرقم 1 يعني بلا تقسيط. الافتراضي: 1.

Success Order Status: حالة الطلب بعد دفع مؤكد. تُضبط الحالة مرة واحدة فورًا، دون تغيير ثانٍ للحالة.

متقدم

Debug log: Log API requests and notifications يكتب إلى WooCommerce > Status > Logs، والمصدر wcp_cardcom_payment_gateway. تُسجَّل الأخطاء دائمًا. ولا تُكتب بيانات الاعتماد ورموز البطاقات وتفاصيل حامل البطاقة أبدًا. الافتراضي: إيقاف.

Delete on Uninstall: Delete all plugin data when uninstalling. عند التفعيل، يؤدي حذف الإضافة إلى إزالة الإعدادات وبيانات Cardcom المحفوظة في الطلبات والسجلات نهائيًا. أما الطلبات نفسها فتبقى. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit Card (Cardcom)) ويقدّم الطلب. تنشئ الإضافة صفحة دفع في Cardcom بإجمالي الطلب وبعملة الطلب، وتنقل العميل إليها. تُفتح الصفحة بالعبرية إذا كانت لغة الموقع العبرية، وإلا فبالإنجليزية. تُمرَّر بنود الطلب إلى Cardcom بوصفها اسم المنتج. يُدخل العميل بيانات البطاقة، ويختار عدد الدفعات إن كان التقسيط مسموحًا.

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

إذا لم تكتمل عملية الدفع، تعيد Cardcom العميل إلى صفحة الدفع (أو صفحة Pay for order)، فتعرض The card payment was not completed. Please try again or choose a different payment method. ويُوضع الطلب في حالة «فشل» عند رفض دفع تؤكده Cardcom. ويمكن للعميل دفع طلب غير مدفوع مرة أخرى، مثلًا من صفحة Pay for order. ويُعترف أيضًا بالدفع الذي تم في صفحة دفع أقدم للطلب نفسه. وإذا غيّر العميل طريقة الدفع إلى أخرى لكنه دفع في صفحة Cardcom، فيُسجَّل الدفع وتُعاد طريقة الدفع إلى Cardcom.

إذا تعذّر على Cardcom فتح صفحة الدفع، يرى العميل رسالة قصيرة، مثل Could not connect to Cardcom. Please try again in a moment. أو رسالة بأن Cardcom تعذّر عليها فتح صفحة الدفع، مع رمز Cardcom، ويمكنه اختيار طريقة دفع أخرى.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

تقبل الإضافة مدفوعات البطاقات في صفحة Cardcom فقط. لا تتضمن البطاقات المحفوظة أو الدفع بنقرة واحدة، ولا الاشتراكات، ولا تخصم الرموز المحفوظة، ولا إعدادات الفواتير أو الإيصالات في Cardcom، ولا Bit أو Apple Pay أو Google Pay أو PayPal عبر Cardcom، ولا وضع iframe، ولا صفقات التحصيل المؤجل. ولا تُفحص صفحات الدفع المهجورة تلقائيًا.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Cardcom ولم يدفع بعد، أو لم تؤكد Cardcom الدفع بعد.

Processing, Completed or On Hold: تم تأكيد الدفع. تتبع الحالة Success Order Status. تعرض ملاحظة الطلب معاملة Cardcom، وعند إرسالها من Cardcom، آخر أربعة أرقام من البطاقة ورقم الفاتورة وعدد الأقساط. وتُعلَّم المدفوعات التجريبية بعبارة Test mode — no real money was charged. ورقم معاملة الطلب هو رقم الصفقة (Deal) في Cardcom.

On hold after payment: أكدت Cardcom دفعة لا تطابق الطلب، مثلًا إذا تغيّر إجمالي الطلب بعد فتح صفحة الدفع، أو خُصم مبلغ أو عملة مختلفان. تشرح ملاحظة الطلب ذلك. قارِن الدفعة في لوحة تحكم Cardcom مع الطلب، ثم نفّذ الطلب أو استرد الدفعة.

Failed: رفضت Cardcom الدفع. تعرض ملاحظة الطلب رمز استجابة Cardcom. ولا يُفشل الرفضُ على صفحة دفع أقدم محاولةً أحدث، ولا يغيّر الرفض المتأخر أي طلب مدفوع أبدًا.

إذا وصلت دفعة ناجحة ثانية لطلب مدفوع بالفعل (مثلًا إذا دفع العميل في تبويبين من المتصفح)، فلا يُغيَّر الطلب مرة أخرى. وتحذّرك ملاحظة من أن العميل قد يكون خُصم منه مرتين، وتطلب منك استرداد المبلغ من لوحة تحكم Cardcom.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Credit Card (Cardcom) (يعرض الزر عنوان طريقة الدفع). يُدعم الاسترداد الكامل والجزئي، ويمكن إجراء عدة استردادات جزئية لطلب واحد. يُرسل الاسترداد ببيانات اعتماد الوضع الذي دُفع فيه الطلب: فتُسترد الطلبات التجريبية عبر طرفية الاختبار في Cardcom حتى بعد أن تنتقل إلى وضع الإنتاج، وتستخدم الطلبات الحقيقية بيانات اعتمادك الحقيقية دائمًا. ويتطلب الاسترداد في وضع الإنتاج API Username وAPI Password. وإذا لم تقبل Cardcom الاسترداد، تعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. وعند نجاح الاسترداد تُضاف معاملته لدى Cardcom والسبب إلى ملاحظات الطلب.

لا تُرسَل الاستردادات التي تُجرى في لوحة تحكم Cardcom إلى المتجر. وإذا لزم الأمر، أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via الخاص بالبوابة.

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

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

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

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

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

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

Cardcom لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن عملة الطلب ILS أو USD أو EUR أو GBP. وفي وضع الإنتاج تحقق من أن Terminal Number وAPI Username مملوءان. تعرض صفحة الإعدادات تحذيرًا عند وجود نقص.

تم الدفع لكن الطلب ما زال Pending payment: لم تستطع Cardcom الوصول إلى موقعك، مثلًا بسبب وضع الصيانة، أو جدار حماية، أو حماية بكلمة مرور، أو موقع تطوير محلي. يجب أن يكون عنوان الإشعار متاحًا من الإنترنت عبر HTTPS. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى صفحة استلام الطلب. فعّل Debug log وراجع WooCommerce > Status > Logs، والمصدر wcp_cardcom_payment_gateway.

يرد الإشعار بالرسالة Missing or invalid lowprofilecode أو Unknown lowprofilecode for this order: لم يتضمن الاستدعاء رمز صفحة دفع صادرًا من متجرك لذلك الطلب. لا يتغير الطلب.

يرد الإشعار بالرسالة Gateway not configured أو Indicator check failed: بيانات الاعتماد الخاصة بالوضع الذي أُنشئت فيه صفحة الدفع ناقصة، أو تعذّر الوصول إلى Cardcom للتحقق. لا يتغير الطلب، ويُعاد فحصه عندما يعود العميل إلى المتجر.

يرد الإشعار بالرسالة ReturnValue mismatch أو Terminal mismatch: أبلغت Cardcom عن دفعة لطلب آخر أو لطرفية أخرى. لا يتغير الطلب. تحقق من أن Terminal Number هو طرفية حسابك.

يرى العميل الرسالة Payment error: this currency is not supported by Cardcom.: عملة الطلب ليست ILS أو USD أو EUR أو GBP.

يرى العميل الرسالة Card payment is temporarily unavailable. Please choose another payment method.: وضع الإنتاج مفعّل، لكن رقم الطرفية أو اسم مستخدم API ناقص.

يرى العميل خطأً عند تقديم الطلب: افتح ملاحظات الطلب، أو فعّل Debug log وراجع السجل. وتُكتب فيه مشكلات الاتصال ورموز أخطاء Cardcom.

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. كان المبلغ المدفوع أو عملته مختلفًا عن الطلب. نفّذ الطلب أو استرد الدفعة.

يفشل الاسترداد برسالة API username and API password are required for refunds: أدخل API Password (وAPI Username) في الإعدادات ثم حاول مجددًا.

يفشل الاسترداد برسالة Could not connect to Cardcom: تحقق من لوحة تحكم Cardcom قبل المحاولة مجددًا، لأن الاسترداد ربما يكون قد تم أو لم يتم.

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

للمطورين: يذكر ملف readme الفلتر cardcom_p_supported_currencies، الذي يوسّع قائمة العملات (أضف العملات المفعّلة في طرفية Cardcom فقط).

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

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

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