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

المتطلبات

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

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

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

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

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

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

التثبيت

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

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

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

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

5. للمدفوعات الحقيقية أوقف Test Mode، وأدخل Terminal Number وAPI Username وAPI Password التي استلمتها من Cardcom، ثم انقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. تعرض الصفحة تحذيرًا فوق الحقول ما دام وضع الاختبار مفعّلًا. وفي وضع الإنتاج تحذّرك إذا كان رقم الطرفية أو اسم مستخدم API مفقودًا (وفي هذه الحالة تُخفى Cardcom عند الدفع)، وإذا كانت حقول الإنتاج تحتوي على الطرفية التجريبية العامة 1000 / CardTest1994 (وفي هذه الحالة تُخفى Cardcom عند الدفع أيضًا، لأنه لن يُخصم أي مبلغ حقيقي)، وتذكّرك بأنه بدون كلمة مرور API لا يمكن إجراء استردادات من PrestaShop. وتحذّرك أيضًا إذا كانت العملة الافتراضية لمتجرك غير مدعومة. وعند حفظ وضع الإنتاج ببيانات اعتماد مفقودة أو بيانات اختبار، تظهر رسالة خطأ تخبرك بأن البوابة تبقى مخفية عند الدفع حتى تُدخل رقم طرفيتك واسم مستخدم API الخاصين بك.

Cardcom

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

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

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

وضع الاختبار

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

Test Mode: يفعّل وضع الاختبار (الطرفية 1000، دون مبالغ حقيقية). الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية باستخدام بيانات الإنتاج أدناه. تُرسل الاستردادات دائمًا ببيانات الوضع الذي دُفع فيه الطلب.

بيانات الإنتاج

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

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

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

API Password: كلمة مرور API الخاصة بك لدى Cardcom. تُطلب فقط للاستردادات من PrestaShop. لا تُعرض كلمة المرور المحفوظة مرة أخرى: يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها.

Clear the saved API password: ضع علامة في المربع وانقر على Save لحذف كلمة المرور. الحقل الفارغ يُبقي القيمة المحفوظة.

صفحة الدفع

Notification URL: ترسل Cardcom إشعارات الدفع (IndicatorUrl) إلى هذا العنوان. مع الروابط الصديقة للمحركات يبدو هكذا: https://your-shop/module/wcp_cardcom_payment_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. يُمرَّر العنوان تلقائيًا إلى Cardcom مع كل دفعة مع معرّف السلة، لذلك لا يلزم إعداد شيء في Cardcom. ويجب أن يكون متاحًا من الإنترنت عبر HTTPS.

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

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

Success Order Status: حالة الطلب بعد دفع مؤكَّد. يُنشأ الطلب مباشرة بهذه الحالة.

تذهب الدفعات التي لا تطابق الطلب دائمًا إلى Cardcom payment on hold.

متقدم

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

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

Delete on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات والسجلات نهائيًا. تبقى الطلبات ومعاملات Cardcom والاستردادات وحالة الطلب Cardcom payment on hold محفوظة دائمًا، لذلك يمكن استرداد الطلبات القديمة بعد إعادة التثبيت. الافتراضي: معطّل.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit Card (Cardcom)) ويرى الملاحظة You will be redirected to the secure Cardcom payment page. بعد التأكيد تُنشئ الوحدة صفحة دفع Cardcom بإجمالي السلة وبعملة السلة، وتُرسل العميل إليها. لا يوجد طلب حتى هذه النقطة. تُفتح الصفحة بالعبرية إذا كانت لغة العميل العبرية، وإلا فبالإنجليزية. تُرسل منتجات السلة إلى Cardcom كاسم للمنتج. يُدخل العميل بيانات بطاقته، ويختار عدد الدفعات إذا كان التقسيط مسموحًا.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب مدفوعًا إلا بعد أن تؤكد Cardcom ذلك. تستدعي Cardcom عنوان الإشعار، وتأخذ الوحدة من هذا الاستدعاء رمز صفحة الدفع فقط. تتحقق من أن هذا الرمز أصدره متجرك لهذه السلة، ثم تطلب من Cardcom النتيجة الحقيقية من خادم إلى خادم. إذا تأخر الإشعار، يُجرى التحقق نفسه عند عودة العميل. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with Cardcom has been received. وإذا لم تؤكد Cardcom الدفع بعد عند عودة العميل، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. مع زر Check again؛ ويُنشأ الطلب فور وصول الإشعار.

إذا لم يكتمل الدفع أو رفضته Cardcom، يعود العميل إلى صفحة الدفع ويرى The card payment was not completed. Please try again or choose a different payment method. لا يُنشأ أي طلب وتبقى السلة محفوظة. يمكن للعميل المحاولة مرة أخرى: تحصل كل محاولة على صفحة دفع جديدة من Cardcom. ما زال الدفع الذي تم في صفحة دفع أقدم للسلة نفسها يُعترف به، ولا يؤثر الرفض في صفحة أقدم على محاولة جديدة.

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

يعمل الإشعار أثناء وضع الصيانة في المتجر، ولا تحجبه قيود الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Cardcom ولم يدفع، أو رُفض الدفع، أو لم تؤكد Cardcom الدفع بعد. لا توجد إلا السلة.

Payment accepted, Delivered or Cardcom payment on hold: تم تأكيد الدفع. تتبع الحالة Success Order Status. يُسجَّل الدفع برقم صفقة Cardcom (deal) كمعرّف للمعاملة. تعرض رسالة خاصة في الطلب معاملة Cardcom، وعندما تُبلغ Cardcom بها، آخر أربعة أرقام من البطاقة ورقم الفاتورة وعدد الأقساط. تُعلَّم المدفوعات التجريبية بـ Test mode — no real money was charged.

Cardcom payment on hold after payment: أكدت Cardcom دفعًا لا يطابق الطلب، على سبيل المثال تغيّرت السلة بعد فتح صفحة الدفع، أو خُصم مبلغ أو عملة مختلفة. تشرح الرسالة ذلك، وتعرضه كتلة Cardcom تحت Needs review. يُسجَّل الدفع بالمبلغ الذي خصمته Cardcom عندما تتطابق العملة مع عملة الطلب. قارن الدفع في لوحة Cardcom بالطلب، ثم أكمل الطلب أو استرد الدفع.

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

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

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

تعرض صفحة الطلب كتلة Cardcom payment تتضمن المعاملة ورمز صفحة الدفع والحالة والبطاقة والأقساط والفاتورة ورمز البطاقة (مع Charge + Save token) والمبلغ المخصوم وإجمالي الطلب والمبلغ المسترد، وشارة Test mode للمدفوعات التجريبية، وسجل الاستردادات.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائن. لا ترسل أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Cardcom. ولا تُبلَّغ الاستردادات التي تتم في لوحة Cardcom إلى المتجر.

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

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

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

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

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

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

تم الدفع، لكن لم يُنشأ أي طلب: لم تتمكن Cardcom من الوصول إلى متجرك، مثلًا بسبب جدار ناري أو حماية بكلمة مرور أو موقع تطوير محلي. يجب أن يكون عنوان الإشعار متاحًا من الإنترنت عبر HTTPS. يُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع. فعّل Debug log وانظر إلى حقل Log في صفحة الوحدة.

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

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

يرد الإشعار بـ Busy, retry: كانت السلة تُؤكَّد بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). فعّل Debug log لمعرفة السبب.

يرد الإشعار بـ ReturnValue mismatch or 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 مفقود، أو أن حقول الإنتاج تحتوي على الطرفية التجريبية العامة.

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

الطلب في حالة Cardcom payment on hold after payment: اقرأ رسالة الطلب أو Needs review في كتلة Cardcom payment. كان المبلغ أو العملة المدفوعان مختلفين عن الطلب. أكمل الطلب أو استرد الدفع.

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

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

للمطورين، يسرد README الخطاف actionCardcomSupportedCurrencies، الذي يوسّع قائمة العملات (أضف فقط العملات المفعّلة في طرفية Cardcom الخاصة بك)، والخطاف actionCardcomLowProfileParams، الذي يغيّر معلمات صفحة الدفع.

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

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

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