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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

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

عند التثبيت، تُنشئ الوحدة حالتين للطلب: Awaiting Klarna fraud review وKlarna payment on hold. ولا تُحتسب أي منهما كمدفوعة، ولا ترسل أي بريد إلكتروني. تقدّم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

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

Klarna Payments

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

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

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

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

تُنشأ بيانات اعتماد Klarna API (اسم المستخدم وكلمة المرور) في Klarna Merchant Portal (portal.klarna.com) ضمن Settings > Klarna API credentials. وتأتي بيانات اعتماد الاختبار من بوابة بيئة الاختبار: playground.eu.portal.klarna.com لأوروبا، وplayground.us.portal.klarna.com لأمريكا الشمالية وأوقيانوسيا.

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

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

Europe: النمسا وبلجيكا وفنلندا وفرنسا وألمانيا واليونان وأيرلندا وإيطاليا وهولندا والبرتغال وسلوفاكيا وإسبانيا (EUR)، والسويد (SEK)، والنرويج (NOK)، والدنمارك (DKK)، والمملكة المتحدة (GBP)، وسويسرا (CHF)، وبولندا (PLN)، والتشيك (CZK)، والمجر (HUF)، ورومانيا (RON). الافتراضي.

North America (US, CA, MX): الولايات المتحدة (USD)، وكندا (CAD)، والمكسيك (MXN).

Oceania (AU, NZ): أستراليا (AUD)، ونيوزيلندا (NZD).

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

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

Test username (UID): اسم مستخدم API لبيئة الاختبار.

Test password: كلمة مرور API لبيئة الاختبار (سر مشترك).

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

Clear saved passwords: حدِّد كلمة المرور وانقر على Save لحذفها. الحقل الفارغ يُبقي القيمة المحفوظة.

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

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

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

When the order is shipped (recommended): يُحصِّل عند نقل الطلب إلى حالة شحن، مثل Shipped أو Delivered (الافتراضي). المبلغ المحصّل هو إجمالي الطلب مطروحًا منه ما سبق تحصيله، ولا يتجاوز المبلغ المعتمد المتبقي. إذا فشل التحصيل، لا تتغير حالة الطلب، ويظهر السبب في صفحة الطلب.

Immediately (auto capture): يخصم من العميل فورًا، للسلع الرقمية أو الخدمات.

Manually in the Klarna portal: لا تُحصِّل الوحدة المبلغ. حصِّل الطلب من Klarna Merchant Portal.

Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. الافتراضي: مفعّل.

الإشعارات

تُبلغ Klarna بنتيجة مراجعة الاحتيال (الطلبات المُقدَّمة كـ"معلّقة") إلى العنوان الظاهر في Notification URL. ومع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_klarna_payment/notification، وقد يتضمن رمز لغة مثل /en/. يُرسل الرابط تلقائيًا مع كل طلب، لذلك لا يوجد ما يُضبط في Klarna. لا يُوثق بمحتوى الإشعار أبدًا: يُتحقق من كل إشعار عبر Klarna Order Management API باستخدام بيانات اعتماد البيئة والمنطقة اللتين أُنشئ فيهما الطلب، ويجب أن يشير طلب Klarna إلى سلة هذا المتجر. تتصرف الوحدة وفقًا لما تُبلغ به Klarna:

ACCEPTED: وافقت Klarna على الشراء. بعد التحقق من المبلغ والعملة يُعلَّم الطلب كمدفوع.

REJECTED or STOPPED: لم يجتز الشراء مراجعة الاحتيال. يتحول الطلب إلى Payment error.

Klarna order CANCELLED, EXPIRED or CLOSED: لم يُخصم من العميل. يُلغى الطلب.

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

متقدم

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

Log: يعرض حجم السجل وأحدث مدخلاته، مع زر لمسحه.

Uninstall: يحذف إعدادات الوحدة والسجل عند إلغاء تثبيت الوحدة. تُحفظ بيانات الطلبات (معرّفات طلبات Klarna، والاستردادات) دائمًا. الافتراضي: إيقاف.

الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا Klarna، مع شارة Klarna)، وتُحمَّل أداة Klarna داخل خطوة الدفع. تُنشئ الوحدة جلسة Klarna من السلة على الخادم. وفي الأداة، يختار العميل الدفع الآن أو لاحقًا أو على أقساط، حسب ما تعرضه Klarna. عندما يُقدِّم العميل الطلب، تُحدَّث جلسة Klarna أولًا بالسلة النهائية، وتعتمد Klarna الشراء داخل الأداة. ثم تُنشئ الوحدة طلب Klarna من جهة الخادم، ببنود الطلب والإجماليات والعناوين الموجودة في السلة. تُرسل خصومات السلة إلى Klarna كبند منفصل. لا يوجد طلب قبل رد Klarna.

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

ACCEPTED: يُنشأ الطلب بحالة Payment accepted، ويرى العميل صفحة تأكيد الطلب المعتادة. يُعتمد المبلغ، ويُحصَّل وفق إعداد Capture.

PENDING: يُنشأ الطلب بحالة Awaiting Klarna fraud review حتى يصل إشعار Klarna. لا تشحنه قبل ذلك.

REJECTED: لا يُنشأ طلب. يبقى العميل في الدفع مع رسالة Klarna could not approve this purchase. Please choose another payment method.

إذا لم تستطع Klarna قبول الطلب، يبقى العميل في الدفع مع رسالة قصيرة، مثل 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.، أو، عند انتهاء صلاحية التفويض، طلب النقر على "Place order" مرة أخرى. تُكتب التفاصيل في السجل. إذا لم تطابق دولة العميل وعملته أي سوق لـ Klarna في منطقتك، يرى العميل Klarna is not available for your billing country and currency. Please choose another payment method.

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

يحمل طلب Klarna في Klarna Merchant Portal رقم السلة كمرجع للتاجر، لأن طلب PrestaShop لا يكون موجودًا بعد عند تقديمه.

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

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

Order statuses

No order yet: لم يُكمل العميل تفويض Klarna، أو رفضت Klarna الشراء. السلة وحدها موجودة.

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

Awaiting Klarna fraud review: الشراء معلّق بانتظار مراجعة الاحتيال من Klarna. ينقل إشعار Klarna الطلب إلى Payment accepted أو Payment error أو Canceled.

Klarna payment on hold: أعادت Klarna حالة احتيال غير متوقعة، أو لم يطابق المبلغ أو العملة اللذان أبلغت عنهما Klarna الطلب. وتشرح الملاحظة السبب. راجع الطلب في Klarna Merchant Portal.

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

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

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

Capture

مع When the order is shipped، يؤدي نقل الطلب إلى حالة شحن إلى تحصيل إجمالي الطلب قبل حفظ الحالة الجديدة. إذا رفضت Klarna التحصيل، مثلًا لأن إجمالي الطلب تجاوز المبلغ المعتمد بعد تعديله، فلا تتغير الحالة، ولا يُرسل أي بريد إلكتروني، ويظهر السبب في صفحة الطلب وفي ملاحظة: العميل لم يُخصم منه أي مبلغ. عالج المشكلة ثم غيّر الحالة مرة أخرى لإعادة المحاولة، أو حصِّل الطلب في Klarna Merchant Portal وغيّر Capture إلى يدوي. في PrestaShop 8 في وضع الإنتاج، قد يحفظ الواجهة الخلفية الحالة مع ذلك؛ عندها تضبط الوحدة بدلًا من ذلك Klarna payment on hold مع ملاحظة، حتى لا يظهر الطلب أبدًا كمشحون دون تحصيل. يضيف التحصيل الناجح ملاحظة تتضمن المبلغ المحصّل ومعرّف التحصيل.

كتلة Klarna payment

تعرض صفحة الطلب كتلة Klarna payment تتضمن معرّف طلب Klarna، وبيئته ومنطقته، وشارة Playground لطلبات الاختبار، وحالة الاحتيال وحالة Klarna، والمبلغ المعتمد، والمبالغ المحصّلة والمستردة، وسجل الاسترداد.

الاسترداد

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

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد المال عبر Klarna. الاستردادات التي تتم في Klarna Merchant Portal لا تُضاف إلى الكتلة، لكنها تُحتسب ضمن المبلغ الذي ما زالت Klarna تسمح باسترداده.

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

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

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

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

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

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

تمت عملية الدفع، لكن الطلب يبقى في Awaiting Klarna fraud review: الشراء معلّق بانتظار مراجعة الاحتيال من 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. تحقق من بيانات اعتماد الوضع النشط، ومن دولة العميل وعملته.

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

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

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

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Klarna Payments، واختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Uninstall مفعّلًا في قسم Advanced، تُحذف إعدادات الوحدة والسجل وجلسات الأداة المؤقتة. وإذا كان موقوفًا، تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ طلبات Klarna واستردادها، وحالتا الطلب Awaiting Klarna fraud review وKlarna payment on hold دائمًا، لذلك يمكن تحصيل الطلبات السابقة واستردادها بعد إعادة التثبيت. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

Klarna علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Klarna ولا معتمدة من قبلها.