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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: تشترط Klarna استخدام HTTPS للمدفوعات الفعلية.

حساب تاجر 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. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، ثم انقر Install Now. يمكنك أيضًا رفع المجلد wcp_klarna_payment إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

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

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

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

6. أدخل اسم المستخدم وكلمة المرور الخاصين بالاختبار من بوابة اختبار Klarna، واترك Test mode مفعّلًا، وفعّل Enable/Disable، ثم نفّذ طلب اختبار.

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

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Klarna Payments. بجوار عنوان الصفحة تظهر شارة TEST MODE أو LIVE. تُظهر الصفحة تحذيرًا عند غياب اسم المستخدم أو كلمة المرور للوضع النشط (وعندها تكون Klarna مخفية في صفحة الدفع)، وعندما لا تبيع Klarna عملة المتجر في منطقة API المحددة. وفي قائمة طرق الدفع تُعرض Klarna على أنها تحتاج إلى إعداد حتى يتم إدخال بيانات الاعتماد للوضع النشط، وتُظهر شارة وضع الاختبار طالما كان وضع الاختبار مفعّلًا.

عام

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: Use the Klarna playground (test credentials, no real payments). الافتراضي: مفعّل. عندما يكون وضع الاختبار مفعّلًا، تعرض صفحة الدفع TEST MODE: Klarna playground, no real payment is made. تحتفظ الطلبات ببيئة إنشائها: تستخدم عمليات تحصيل الطلبات الاختبارية واستردادها بيانات اعتماد الاختبار دائمًا.

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

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

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

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

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

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

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

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

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

الإشعارات

تُرسل Klarna نتيجة مراجعة الاحتيال (الطلبات المُسجَّلة كـ"pending") إلى عنوان URL للإشعارات المعروض في هذا القسم. يبدو هكذا: https://your-site/wc-api/wc_kl_payment/. يُرسل العنوان تلقائيًا مع كل طلب، فلا يلزم إعداد أي شيء في Klarna. لا يُوثق بمحتوى الإشعار أبدًا: يُتحقق من كل إشعار عبر Klarna Order Management API، ويجب أن يشير طلب Klarna إلى طلب هذا المتجر. تتصرف الإضافة وفق ما تُبلغ به Klarna:

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

متقدم

Debug log: Log API calls and payment events في WooCommerce > Status > Logs، المصدر wcp_klarna_payment. تُسجَّل الأخطاء دائمًا. لا تحتوي السجلات على بيانات الاعتماد أو بيانات العملاء أبدًا. الافتراضي: معطّل.

Uninstall: Delete the plugin settings and logs when the plugin is deleted. تُحتفظ بيانات الطلبات (معرّفات طلبات Klarna) دائمًا. الافتراضي: معطّل.

الدفع

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

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

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

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

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

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

حالات الطلب

Processing or Completed: وافقت Klarna على عملية الشراء. تضبط WooCommerce الحالة المعتادة للطلب المدفوع. تعرض ملاحظة الطلب معرّف طلب Klarna والوقت الذي سيُحصَّل فيه. معرّف المعاملة هو معرّف طلب Klarna. عند تحصيل الطلب تعرض ملاحظة المبلغ المُحصَّل ومعرّف التحصيل.

On hold: عملية الشراء في انتظار مراجعة الاحتيال، أو أعادت Klarna حالة احتيال غير متوقعة، أو لم يتطابق المبلغ أو العملة التي أبلغت بها Klarna مع الطلب، أو فشل التحصيل. تشرح ملاحظات الطلب السبب.

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

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

التحصيل

مع When the order is Completed، يؤدي تعليم الطلب كـ"مكتمل" إلى تحصيل إجمالي الطلب. إذا فشل التحصيل، مثلًا لأن إجمالي الطلب تجاوز المبلغ المفوَّض بعد تعديله، يُوضع الطلب في الانتظار مع ملاحظة تفيد بأن العميل لم يُخصم منه شيء، ولا يتلقى العميل بريد "الطلب المكتمل". أصلح المشكلة ثم علِّم الطلب كـ"مكتمل" مجددًا لإعادة المحاولة، أو حصِّل المبلغ من Klarna Merchant Portal.

الاسترداد

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Klarna Payments. تُدعم الاستردادات الكاملة والجزئية للمبالغ المحصّلة، حتى حدود المبلغ المحصّل مطروحًا منه ما سبق استرداده. يُرسل الاسترداد إلى البيئة والمنطقة اللتين أُنشئ فيهما الطلب، لذلك يجب ضبط بيانات اعتماد تلك البيئة. إذا لم تقبل Klarna الاسترداد، تعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف استرداد Klarna. ولا يُنفَّذ الاسترداد المُعاد محاولته مرتين أبدًا.

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

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

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

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

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

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

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

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

تمت عملية الدفع لكن الطلب ما زال On hold: عملية الشراء في انتظار مراجعة الاحتيال لدى Klarna، وسيُحدَّث الطلب عند وصول إشعار Klarna. تحقّق من أن موقعك يستطيع استقبال طلبات Klarna على عنوان URL للإشعارات المعروض في الإعدادات، وأن بيانات اعتماد البيئة التي أُنشئ فيها الطلب ما زالت مُدخلة. راجع WooCommerce > Status > Logs، المصدر wcp_klarna_payment.

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

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

يرد الإشعار بـ mismatch_ref: طلب Klarna لا يشير إلى هذا الطلب في المتجر. لا يُعدَّل الطلب.

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

فشل التحصيل، والطلب On hold: اقرأ ملاحظة الطلب. قد يحتاج إجمالي الطلب إلى أكثر من المبلغ المفوَّض المتبقي، أو قد لا يكون طلب Klarna مقبولًا بعد، أو ربما انتهت صلاحية التفويض. أصلح المشكلة وعلِّم الطلب كـ"مكتمل" مجددًا، أو حصِّله من Klarna Merchant Portal.

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

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

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

تعطيل الإضافة يُبقي جميع البيانات. لحذفها، عطّلها ثم احذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة والسجلات (المصدر wcp_klarna_payment) فتُحذف فقط إذا كان Uninstall (Delete the plugin settings and logs when the plugin is deleted) مفعّلًا. وإلا فستبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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