VibeFox Klarna for OpenCart — المساعدة

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو الإصدار 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

حساب تاجر Klarna: تحتاج إلى بيانات اعتماد Klarna API (اسم المستخدم وكلمة المرور) لحساب التاجر الخاص بك في منطقة API واحدة، وبيانات اعتماد الاختبار من بوابة Klarna Playground (راجع الإعداد). لكل منطقة API بيانات اعتماد خاصة بها. يمكن استخدام حساب تاجر واحد فقط (منطقة API واحدة) لكل متجر.

العملة: عملة Klarna من منطقتك: EUR أو SEK أو NOK أو DKK أو GBP أو CHF أو PLN أو CZK أو HUF أو RON في أوروبا؛ أو USD أو CAD أو MXN في أمريكا الشمالية؛ أو AUD أو NZD في أوقيانوسيا. يجب أن تكون العملة موجودة في System > Localisation > Currencies.

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

التثبيت

يحتوي هذا التنزيل على ملف zip واحد فيه حزم الإصدارين من OpenCart. فُكّه على حاسوبك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_klarna_payment-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_klarna_payment.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف wcp_klarna_payment-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا تحتاج Extensions > Modifications إلى التحديث. وبدلاً من أداة التثبيت، يمكنك أيضاً نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم ابحث عن VibeFox Klarna Payments واضغط Install (الزر الأخضر +). يحتاج مستخدم المدير لديك إلى صلاحية تعديل قائمة إضافات الدفع.

3. اضغط Edit (زر القلم) لفتح صفحة الإعدادات. ألصق مفتاح ترخيص VibeFox في License key ضمن كتلة الترخيص في أعلى الصفحة، ثم اضغط Activate (راجع مفتاح الترخيص).

4. اختر API region لحساب التاجر في Klarna.

5. أدخل اسم المستخدم وكلمة المرور الخاصين بالاختبار من بوابة Klarna Playground، وأبقِ Test mode مفعّلاً، وفعّل Enable/Disable، ثم اضغط Save ونفّذ طلباً تجريبياً.

6. أدخل اسم المستخدم وكلمة المرور الخاصين بالإنتاج من Klarna Merchant Portal، وألغِ تفعيل Test mode، واختر وقت تحصيل الطلبات (الافتراضي: عند شحن الطلب أو إتمامه).

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف wcp_klarna_payment.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الامتداد من اسم الملف، ولا تعمل الحزمة إذا أُعيد تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. اضغط Install (الزر الأخضر +) بجانبها.

3. انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم ابحث عن VibeFox Klarna Payments واضغط Install (الزر الأخضر +)، ثم Edit (زر القلم).

4. أدخل مفتاح الترخيص وAPI region وبيانات الاعتماد ووضع التحصيل كما في الخطوات من 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو عنوان Notification URL (راجع الإشعارات).

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

الإعداد

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Klarna Payments > Edit. تُدرج الأقسام على اليسار؛ يحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات، تعرض الصفحة TEST MODE: Klarna playground, no real payments. أو LIVE: real Klarna payments. وتحذّرك إذا كان اسم المستخدم أو كلمة المرور للوضع النشط مفقودين (فيُخفى Klarna عندئذٍ في الدفع)، وإذا كانت العملة الافتراضية للمتجر غير مدعومة من Klarna في منطقة API المحددة. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب ألا يكون Title فارغاً (بحد أقصى 128 حرفاً)، ويجب أن يكون Sort Order رقماً صحيحاً (الأرقام السالبة مسموحة)، ويجب أن يكون Total رقماً أكبر من 0 أو مساوياً له، ويجب أن تكون منطقة API ووضع التحصيل والمنطقة الجغرافية وحالات الطلب صالحة. وإلا فلن يُحفظ أي شيء، وستذكر الصفحة الحقل المعني. ولا تمنع بيانات الاعتماد المفقودة الحفظ.

مدفوعات Klarna

Enable/Disable: يفعّل طريقة الدفع أو يعطّلها. الافتراضي: معطّل. لا يظهر Klarna في الدفع إلا عندما يكون اسم المستخدم وكلمة المرور للوضع النشط مملوءين، وتكون دولة الفوترة لدى العميل سوقاً من أسواق Klarna في منطقة API، ويكون الدفع بعملة تلك الدولة.

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضاً اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Klarna. مطلوب.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، أعلى أداة Klarna. الافتراضي: Pay now, later or in instalments with Klarna.

Sort Order: موضع Klarna بين طرق الدفع عند الدفع. اتركه فارغاً أو أدخل رقماً صحيحاً.

Geo Zone: اعرض Klarna فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Klarna. اتركه فارغاً لعرض Klarna عند أي مبلغ.

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

تُنشأ بيانات اعتماد Klarna API (اسم المستخدم وكلمة المرور) في Klarna Merchant Portal ضمن Settings > Klarna API credentials (توجد روابط القسم هناك). تأتي بيانات اعتماد الاختبار من بوابة Playground: واحدة لأوروبا، وأخرى لأمريكا الشمالية وأوقيانوسيا. لكل منطقة API بيانات اعتماد خاصة بها.

Test mode: يستخدم بيئة Klarna Playground (بيانات اعتماد اختبار، ولا توجد مدفوعات حقيقية). الافتراضي: مفعّل. أثناء تفعيل وضع الاختبار، يرى العملاء في خطوة Confirm Order العبارة TEST MODE: Klarna playground, no real payment is made.. تحتفظ الطلبات بالبيئة التي أُنشئت فيها: تستخدم عمليات التحصيل والاسترداد لطلبات Playground دائماً بيانات اعتماد الاختبار.

API region: منطقة حساب التاجر في Klarna. يمكن للعملاء الدفع بـ Klarna فقط من دول هذه المنطقة، وبعملة بلدهم. يُؤخذ البلد من عنوان الدفع في الطلب.

Live username (UID): اسم مستخدم API الخاص بالإنتاج، مثل PK12345_abcdef012345.

Live password: كلمة مرور API الخاصة بالإنتاج (سرّ مشترك).

Test username (UID): اسم مستخدم API الخاص بـ Playground.

Test password: كلمة مرور API الخاصة بـ Playground (سرّ مشترك).

لا تُعرض كلمات المرور المحفوظة مرة أخرى. يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it.. أدخل قيمة جديدة فقط إذا أردت تغييرها. لإزالة كلمة مرور محفوظة، حدد Clear the saved password on save أسفل الحقل، ثم اضغط Save.

إدارة الطلبات

الطلب المنفَّذ عبر Klarna هو تفويض: لا يُخصم من العميل إلا عند تحصيل الطلب. تنتهي التفويضات غير المحصّلة عادةً بعد 28 يوماً، لذا أرسل الطلبات في الوقت المناسب أو استخدم التحصيل التلقائي.

Capture: الوقت الذي يُخصم فيه المبلغ من العميل. لا يمكن الاسترداد إلا للمبالغ المحصّلة.

Cancellation: يلغي طلب Klarna (ويحرر التفويض) عندما يُعيَّن طلب لم يُحصَّل بعد إلى Canceled Status الموضح أدناه. الافتراضي: مفعّل.

حالات الطلب

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تنشئ Klarna طلب Klarna للعملية المعتمدة في الأداة. العملية التي لا توافق عليها Klarna تترك الطلب دون حالة، ويبقى العميل في خطوة Confirm Order. يسرد كل حقل أدناه حالات طلبات OpenCart لديك.

Order Status After Payment: قبلت Klarna عملية الشراء (حالة الاحتيال ACCEPTED). يُفوَّض المبلغ ويُحصَّل وفق Capture. الافتراضي: Processing.

Awaiting Fraud Review Status: سجّلت Klarna الطلب بحالة PENDING (مراجعة الاحتيال). لا ترسله قبل أن يقبله إشعار Klarna؛ ويتحدّث الطلب تلقائياً. الافتراضي: Pending.

On Hold Status: أعادت Klarna حالة احتيال غير متوقعة، أو لم تطابق المبلغ أو العملة التي أبلغت عنها Klarna الطلب. تشرح ملاحظة ما يجب التحقق منه. الافتراضي: Pending.

Payment Error Status: رفضت Klarna عملية الشراء أو أوقفتها بعد مراجعة الاحتيال. لا ترسل الطلب. الافتراضي: Failed.

Canceled Status: يؤدي تعيين طلب لم يُحصَّل بعد إلى هذه الحالة إلى إلغاء طلب Klarna (راجع Cancellation). كما تُعيَّن هذه الحالة عندما تُبلغ Klarna بأن طلب Klarna ملغى أو منتهٍ أو مغلق. الافتراضي: Canceled.

Refunded Status: أُرجع المبلغ المحصّل بالكامل في تبويب Klarna في صفحة الطلب. تضيف الاستردادات الجزئية ملاحظة فقط. الافتراضي: Refunded.

لا يحتوي OpenCart على حالات خاصة به لمراجعة الاحتيال أو للدفعات المعلّقة. يمكنك إنشاؤها في System > Localisation > Order Statuses واختيارها هنا.

الإشعارات

تُبلغ Klarna بنتيجة مراجعة الاحتيال (الطلبات المسجّلة كمعلّقة) إلى العنوان المعروض في Notification URL. في OpenCart 3 يبدو بهذا الشكل: https://your-store/index.php?route=extension/payment/wcp_klarna_payment/notification، وفي OpenCart 4 بهذا الشكل: https://your-store/index.php?route=extension/wcp_klarna_payment/payment/wcp_klarna_payment.notification. يُرسل العنوان تلقائياً مع كل طلب، لذا لا يلزم إعداد أي شيء في Klarna. لا يُوثَق بمحتوى الإشعار أبداً: يُتحقق من كل إشعار عبر Klarna Order Management API باستخدام بيانات اعتماد البيئة والمنطقة اللتين أُنشئ فيهما الطلب، ويجب أن يشير طلب Klarna إلى رقم الطلب هذا. تتصرف الإضافة بناءً على ما تبلغ به Klarna:

إذا قبلت Klarna عملية شراء بعد أن ألغيت الطلب أو استرددته، فلن يُعاد فتح الطلب وسيُحرَّر تفويض Klarna. يعمل الإشعار أثناء وجود المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة في OpenCart 4 startup action يسمح بمرور الإشعار وعودة العميل من Klarna.

متقدم

Debug log: يسجّل استدعاءات API وأحداث الدفع في wc_kl_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائماً. لا يحتوي السجل أبداً على بيانات اعتماد أو رموز تفويض أو بيانات عملاء. الافتراضي: معطّل.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى إزالة إعدادات البوابة والسجل وجلسات الأداة المؤقتة. تبقى بيانات الطلبات (معرّفات طلبات Klarna والاستردادات) محفوظة دائماً. الافتراضي: معطّل.

الاستيراد / التصدير

Export: يحفظ Download JSON الإعدادات في ملف JSON. لا تُصدَّر كلمات المرور.

Import: ألصق ملف JSON مُصدَّراً سابقاً واضغط Import لاستعادة الإعدادات. تبقى كلمات المرور المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضياً Klarna). ينشئ OpenCart الطلب في خطوة Confirm Order، ولا يزال دون حالة. في هذه الخطوة يرى العميل شارة Klarna ووصفك وأداة Klarna. تنشئ الإضافة جلسة Klarna على الخادم من هذا الطلب: المنتجات مع خياراتها، وبطاقات الهدايا، والشحن، وخصومات القسائم والكوبونات ونقاط المكافآت، والضرائب، والعناوين. في الأداة يختار العميل الدفع الآن أو الدفع لاحقاً أو التقسيط، حسبما تقدّمه Klarna. عندما ينقر العميل Confirm Order، تفوّض Klarna عملية الشراء في الأداة، وتنشئ الإضافة طلب Klarna على الخادم باستخدام بيانات طلب OpenCart. يحمل طلب Klarna رقم طلب OpenCart بوصفه المرجع لدى التاجر.

في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، داخل النافذة Payment method options. تظهر أداة Klarna بعد ذلك في كتلة تأكيد الطلب أسفل صفحة الدفع، فوق زر Confirm Order. لا توجد في OpenCart 4 بطاقات هدايا، لذلك لا تُرسل إلى Klarna. وبشكل افتراضي لا يطلب OpenCart 4 عنوان الدفع؛ عندها تستخدم الإضافة عنوان الشحن كعنوان للفوترة ودولته كدولة للشراء.

تعتمد النتيجة على حالة الاحتيال لدى Klarna:

إذا تعذّر على Klarna قبول الطلب، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة، مثل Klarna could not accept this order. Please check your billing details or choose another payment method. أو Klarna did not respond. Please try again in a moment. أو، عندما تنتهي صلاحية التفويض، طلباً بالنقر على "Confirm Order" مرة أخرى. تُكتب التفاصيل في السجل ويحصل الطلب على ملاحظة. إذا لم تتطابق دولة العميل وعملته مع أي سوق Klarna في منطقتك، يرى العميل Klarna is not available for your billing country and currency. Please choose another payment method.

النقر مرتين، أو إعادة تحميل الصفحة، أو دفع السلة نفسها في تبويب متصفح ثانٍ لا ينشئ أبداً طلب Klarna ثانياً (ينشئ OpenCart 3 طلباً جديداً في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيُحدِّث طلب الدفع في صفحة الدفع، فيدفع العميل الطلب نفسه من جديد بعد الرفض). إذا وافقت Klarna على عملية الشراء لكن تعذّر تعيين حالة الطلب، يرى العميل Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. وتعيّن المحاولة التالية أو إشعار Klarna الحالة من طلب Klarna المحفوظ دون تفويض جديد. ويُحسب تغيير السلة، بما فيه الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تظهر صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلاً ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. وإذا كان الطلب قد تم تقديمه بالفعل وتغيّرت السلة، فالرسالة هي Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. وفي الحالتين، يدفع Confirm Order التالي طلباً جديداً للسلة. وتظهر هذه الرسائل أعلى صفحة الدفع.

لا تتضمن الإضافة Klarna Checkout (KCO، أي استبدال الدفع بالكامل)، ولا أزرار Klarna Express Checkout، ولا On-site messaging أو Sign in with Klarna، ولا الاشتراكات أو طرق الدفع المحفوظة، ولا التحصيل الجزئي لكل بند من بنود الطلب. لا تُرسَل بنود الطلب إلى Klarna مرة أخرى عندما تعدّل طلباً بعد تنفيذه.

الطلبات والمرتجعات

حالات الطلب

No status (missing order): لم يُكمل العميل تفويض Klarna، أو رفضت Klarna عملية الشراء. تظهر هذه الطلبات في Sales > Orders فقط عند ضبط فلتر Order Status على Missing Orders.

Order Status After Payment (default Processing): قبلت Klarna عملية الشراء. تعرض ملاحظة معرّف طلب Klarna وموعد تحصيله.

Awaiting Fraud Review Status (default Pending): عملية الشراء في انتظار مراجعة الاحتيال لدى Klarna. ينقل إشعار Klarna الطلب إلى Order Status After Payment أو Payment Error Status أو Canceled Status.

On Hold Status (default Pending): أعادت Klarna حالة احتيال غير متوقعة، أو لم تطابق المبلغ أو العملة التي أبلغت عنها Klarna الطلب. تشرح الملاحظة ذلك. تحقّق من الطلب في Klarna Merchant Portal.

Payment Error Status (default Failed): رفضت Klarna عملية الشراء أو أوقفتها بعد مراجعة الاحتيال. لا ترسل الطلب.

Canceled Status (default Canceled): ألغيت الطلب بنفسك، أو تُبلغ Klarna بأن طلب Klarna ملغى أو منتهٍ أو مغلق. مع تفعيل Cancellation، يؤدي إلغاء طلب لم يُحصَّل بعد إلى إلغاء طلب Klarna وتحرير التفويض، فلا يُخصم من العميل أي مبلغ. لا يُلغى الطلب المحصّل بالفعل لدى Klarna: استرده لإعادة المال.

Refunded Status (default Refunded): استُرد المبلغ المحصّل بالكامل عبر الإضافة.

الملاحظات هي إدخالات في History الطلب لا يراها العميل. وتبدأ بكلمة Klarna.

Capture

مع When the order is shipped / completed، يؤدي تغيير حالة طلب في Sales > Orders (عبر Add History) إلى حالة مكتملة إلى تحصيل إجمالي الطلب قبل حفظ الحالة الجديدة. إذا رفضت Klarna التحصيل، مثلاً لأن إجمالي الطلب ارتفع فوق المبلغ الذي لا يزال مفوّضاً بعد تعديل الطلب، فلن تتغير الحالة ولن تُرسل أي رسالة بريد إلكتروني، وستعرض صفحة الطلب السبب بدلاً من رسالة النجاح. تذكر الملاحظة أن العميل لم يُخصم منه أي مبلغ. عالج المشكلة ثم غيّر الحالة مرة أخرى لإعادة المحاولة، أو حصّل المبلغ في Klarna Merchant Portal وغيّر Capture إلى يدوي. يضيف التحصيل الناجح ملاحظة تتضمن المبلغ المحصّل ومعرّف التحصيل. لا يُحصّل المبلغ عند الحالة الأولى لطلب جديد، ولا عند الانتقال من حالة مكتملة إلى حالة مكتملة أخرى. تستمر عمليات التحصيل والإلغاء في العمل ما دامت الإضافة مثبّتة، حتى لو كانت معطّلة. في OpenCart 4.1 يعرض سبب رفض تغيير الحالة في صفحة الطلب أيضاً؛ وفي OpenCart 4.0.x تُرفض الحالة كذلك، لكن السبب يظهر فقط في ملاحظة سجل الطلب.

تبويب VibeFox Klarna Payments

في Sales > Orders افتح طلباً مدفوعاً عبر Klarna. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Klarna Payments معرّف طلب Klarna مع بيئته ومنطقته، وتسمية Playground لطلبات الاختبار، وحالة الاحتيال وحالة Klarna، والمبلغ Authorized، والمبالغ Captured / refunded، ونموذج الاسترداد، وسجل الاسترداد، وKlarna notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox Klarna Payments أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد تلقائياً)، واختيارياً Reason (optional)، ثم اضغط Refund via Klarna. أكّد السؤال Refund this amount through Klarna? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة للمبالغ المحصّلة، حتى المبلغ الذي تُبلغ Klarna بأنه محصّل مطروحاً منه ما استُرد سابقاً. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يُرسل الاسترداد إلى البيئة والمنطقة اللتين أُنشئ فيهما الطلب، لذلك يجب ضبط بيانات اعتماد تلك البيئة. إذا لم تقبل Klarna الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع معرّف استرداد Klarna. يضبط الاسترداد الكامل الطلب على Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، كما في تغيير الحالة يدوياً. لا يغيّر الاسترداد الجزئي الحالة. ولا يُنفَّذ الاسترداد المُعاد محاولته مرتين أبداً.

لا يمكن استرداد طلب لم يُحصَّل بعد: ألغِه بدلاً من ذلك لتحرير التفويض. ومع ضبط Capture على يدوي، لا يعرف المتجر ما حصّلته في Klarna Merchant Portal. عندئذٍ يظهر نموذج الاسترداد بمبلغ فارغ، وتتحقق Klarna من المبلغ عند الإرسال.

لا تُعيد المرتجعات في Sales > Returns المال عبر Klarna. لا تُضاف الاستردادات التي أُجريت في Klarna Merchant Portal إلى التبويب، لكنها تُحسب ضمن المبلغ الذي لا تزال Klarna تسمح باسترداده.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Klarna Payments هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Klarna Payments > Edit، فوق الإعدادات. ألصق المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مموّهاً، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-klarna ورابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا مستخدمو المدير الذين لديهم صلاحية Modify على الإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتتضمن الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

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

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

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

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

لا يظهر Klarna عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن بيانات اعتماد الوضع النشط مملوءة: اسم المستخدم وكلمة المرور الخاصان بالاختبار في وضع الاختبار، والخاصان بالإنتاج في الوضع المباشر. تعرض صفحة الإعدادات تحذيراً عند غيابهما. يجب أن تكون دولة دفع العميل دولة Klarna ضمن API region لديك، والدفع بعملة تلك الدولة (مثلاً يجب أن يدفع العميل في السويد بعملة SEK). تحقق أيضاً من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمت عملية الدفع لكن الطلب يبقى في Awaiting Fraud Review Status: عملية الشراء في انتظار مراجعة الاحتيال لدى Klarna، وسيتحدّث الطلب عند وصول إشعار Klarna. تحقق من أن متجرك يستطيع استقبال طلبات Klarna على Notification URL المعروض في الإعدادات، وأن بيانات اعتماد البيئة التي أُنشئ فيها الطلب ما زالت مدخلة. فعّل Debug log وانظر إلى الحقل Log في صفحة الإضافة.

يجيب الإشعار بـ Not configured: بيانات اعتماد البيئة (الاختبار أو الإنتاج) التي أُنشئ فيها الطلب مفقودة، لذلك لا يمكن التحقق من الإشعار. أدخلها. ستعيد Klarna محاولة الإشعار.

يجيب الإشعار بـ Verification failed: تعذّرت قراءة طلب Klarna من Order Management API. ستعيد Klarna محاولة الإشعار.

يجيب الإشعار بـ Busy: كان طلب آخر يحدّث الطلب في اللحظة نفسها. ستعيد Klarna محاولة الإشعار.

يجيب الإشعار بـ mismatch_ref أو Unknown order: طلب Klarna لا يشير إلى هذا الطلب، أو الإضافة لا تعرفه. لا يُعدَّل الطلب.

لا تُحمَّل الأداة: يرى العميل Klarna could not be loaded. Please try again or choose another payment method. أو Klarna is not available for this purchase. تحقق من بيانات اعتماد الوضع النشط، ومن دولة العميل وعملته.

يُرفض تغيير الحالة إلى Complete أو Shipped: فشل تحصيل Klarna. اقرأ السبب في صفحة الطلب أو في الملاحظة. قد يحتاج إجمالي الطلب إلى أكثر من المبلغ المفوَّض، أو قد لا يكون طلب Klarna مقبولاً بعد، أو قد تكون صلاحية التفويض قد انتهت. عالج المشكلة وغيّر الحالة مرة أخرى، أو حصّل المبلغ في Klarna Merchant Portal.

فشل الاسترداد: اقرأ الرسالة في التبويب. قد لا يكون الطلب محصّلاً بعد (ألغِه بدلاً من ذلك)، أو قد يتجاوز المبلغ ما لا يزال قابلاً للاسترداد، أو قد تكون بيانات اعتماد بيئة الطلب مفقودة.

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

يرى العميل This order is already being paid: يوجد طلب آخر لعملية الشراء نفسها قيد التنفيذ، مثل النقر المزدوج. انتظر لحظة وتحقّق مما إذا كان الطلب قد حصل على حالة.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم اضغط Uninstall (الزر الأحمر −) بجوار VibeFox Klarna Payments. يتم دائماً حذف مفتاح ترخيص هذه الإضافة وحالة الترخيص. يحذف OpenCart دائماً إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلب في قسم Order statuses، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما تُحذف أحداث OpenCart الخاصة بالإضافة، فلم تعد تغييرات الحالة تحصّل طلبات Klarna أو تلغيها (وفي OpenCart 4 أيضاً الـ startup action الذي يسمح بمرور الإشعار وعودة العميل في وضع الصيانة). إذا كان Delete data on uninstall مفعّلاً، تُحذف بقية إعدادات البوابة (العنوان، والوصف، ووضع الاختبار، ومنطقة API، وبيانات الاعتماد، والتحصيل، والإلغاء، والتسجيل)، والسجل، وجلسات الأداة المؤقتة. وإذا كان معطّلاً، تبقى لاستخدامها عند إعادة التثبيت لاحقاً. تُحفظ طلبات Klarna واستردادها دائماً، لذلك يمكن تحصيل الطلبات السابقة واسترداد مبالغها بعد إعادة التثبيت. تحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لإزالة ملفات الإضافة أيضاً، انتقل بعد إلغاء التثبيت إلى Extensions > Installer، واضغط Uninstall (الزر البرتقالي −) بجانب VibeFox Klarna Payments في قائمة الإضافات المثبتة، ثم Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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