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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد SimpleXML. لا تسمح الوحدة بالتثبيت من دونهما.

حساب DPO Pay: تحتاج إلى Company Token وService Type ID لحساب التاجر لديك في DPO. تصدرهما DPO عند فتح حسابك؛ اطلبهما من مدير حسابك في DPO أو من dpogroup.com. يمكن لـ DPO أيضًا توفير حساب اختبار بـ token وservice type خاصين به. لا يوجد خادم اختبار منفصل: تستخدم DPO عنوان API نفسه للحسابات التجريبية والفعلية، ويُختار الحساب بحسب الـ token.

العملة: يجب أن تكون عملة المتجر مدعومة من حساب DPO الخاص بك. تقبل DPO بحد أقصى منزلتين عشريتين، لذلك لا يمكن دفع إجماليات السلة ذات ثلاث منازل عشرية (مثل KWD 12.345).

cron على الخادم: مهمة cron تستدعي عنوان الفحص الخاص بالوحدة كل 15 دقيقة (انظر Configuration).

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

التثبيت

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

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

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

4. أدخل Company Token وService Type للاختبار و/أو الحساب الفعلي (انظر Configuration).

5. أرسل عنوان الإشعار الفوري (push) المعروض في صفحة Configure إلى دعم DPO واطلب منهم ضبطه لحسابك. أضف عنوان cron إلى مهام cron على خادمك.

6. فعّل Enable/Disable وانقر على Save. أجرِ طلب اختبار في وضع الاختبار، ثم أوقف Test mode لقبول المدفوعات الحقيقية.

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

Configuration

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox DPO Pay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. عندما تكون الوحدة مفعّلة لكن Company Token أو Service Type للوضع المختار فارغ، تحذرك الصفحة من أن طريقة الدفع ستكون مخفية في الدفع، ويظهر التحذير نفسه عند الحفظ. وما دام وضع الاختبار مفعّلًا، تعرض الصفحة Test mode is on: payments are created with the test account credentials.

DPO Pay

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

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

Description: النص المعروض أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely by card or mobile money on the DPO Pay payment page.

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

تصدر DPO Company Token وService Type ID لحساب التاجر الخاص بك، وقيمًا منفصلة لحساب الاختبار. احصل عليها من مدير حسابك في DPO أو من dpogroup.com.

Test mode: عند التفعيل، تُنشأ المدفوعات الجديدة باستخدام Company Token وService Type الخاصين بالاختبار. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية ببيانات الاعتماد الفعلية. فحوص الحالة وإلغاء المدفوعات القائمة تستخدم دائمًا الحساب الذي أُنشئت به الدفعة.

Test Company Token: Company Token لحساب الاختبار الخاص بك في DPO.

Test Service Type: Service Type ID الرقمي لحساب الاختبار الخاص بك في DPO.

Live Company Token: Company Token لحساب التاجر الفعلي الخاص بك في DPO.

Live Service Type: Service Type ID الرقمي لحساب التاجر الفعلي الخاص بك في DPO.

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

Clear saved Company Tokens: حدّد token ثم انقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

إشعارات الدفع

Push notification URL: يُبلغ الإشعار الفوري متجرك فورًا بأن الدفعة قد تمت، حتى إذا أغلق العميل المتصفح بعد الدفع. لا يُضبط هذا العنوان في لوحة تحكم: اطلب من دعم DPO ضبطه لحسابك. مع الروابط الصديقة يبدو هكذا: https://your-shop/module/wcp_dpo_pay/notify، وربما مع رمز اللغة. انسخه تمامًا كما تعرضه الصفحة. يجب أن يكون متاحًا من الإنترنت، من دون وضع الصيانة أو جدار حماية أو مصادقة أساسية أمامه.

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

Scheduled status re-check (cron): استدعِ هذا العنوان كل 15 دقيقة من مهمة cron على الخادم، مثلًا باستخدام curl. تُعاد مراجعة الدفعات غير المؤكدة لدى DPO بعد 15 دقيقة من إعادة التوجيه، ومرة أخرى بعد انتهاء المهلة المحددة للدفع. يحتوي العنوان على رمز سري، فاحرص على إبقائه خاصًا. من دون عنوان الإشعار الفوري وcron، لا يُنشأ الطلب إلا عند عودة العميل إلى المتجر بعد الدفع.

الطلبات

Successful payment status: حالة الطلب بعد دفعة ناجحة تم التحقق منها.

فروق المبلغ أو العملة، والدفعات المفوَّضة فقط، والمعاملات التي دُفع فيها أكثر أو أقل من المطلوب تذهب دائمًا إلى DPO payment on hold.

متقدم

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

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

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

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده DPO: تطلب الوحدة نتيجة المعاملة من DPO عند عودة العميل، وعند وصول إشعار فوري، وفي الفحوص المجدولة. عندها فقط يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة.

إذا لم يتم تأكيد الدفعة، يعود العميل إلى الدفع مع إحدى هذه الرسائل. تبقى السلة محفوظة.

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

عندما يدفع العميل مرة أخرى للسلة نفسها، تُفحص معاملة DPO السابقة أولًا. إذا كانت مدفوعة يُنشأ الطلب من دون خصم ثانٍ. إذا كانت ما تزال قيد المعالجة، يرى العميل Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again. وإلا تُلغى المعاملة القديمة لدى DPO وتُنشأ معاملة جديدة.

إذا تعذّر على DPO بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة تُختار بحسب رمز خطأ DPO، مثل DPO Pay does not support the currency of this order. Please choose another payment method. أو The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. وتعرض الأخطاء الأخرى DPO Pay is temporarily unavailable. Please try again or choose another payment method. ويُكتب السبب التقني في السجل.

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

تقبل الوحدة الدفعات لمرة واحدة فقط في صفحة DPO. لا تتضمن استردادات من المتجر، ولا بطاقات محفوظة، ولا اشتراكات أو دفعات متكررة، ولا حقول بطاقة في موقعك، ولا تحصيلًا للدفعات المفوَّضة فقط.

الطلبات

حالات الطلب

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

Payment accepted, Delivered or DPO payment on hold: تم التحقق من الدفعة. تتبع الحالة Successful payment status. تُسجَّل الدفعة برمز معاملة DPO كمعرّف للمعاملة. تعرض ملاحظة خاصة في صفحة الطلب المبلغ والعملة ورمز الموافقة وبداية الرمز.

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

Cancelled: عندما تلغي طلبًا غير مدفوع من الوحدة (مثلًا طلبًا معلقًا بسبب دفعة مفوَّضة فقط)، تُلغى معاملة DPO المفتوحة الخاصة به لدى DPO أيضًا.

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

الاستردادات

الاستردادات من المتجر غير متاحة في هذا الإصدار. استرد الدفعة في بوابة تاجر DPO، ثم غيّر حالة الطلب في PrestaShop.

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

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

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

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

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

DPO Pay does not appear at checkout: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن Company Token وService Type للوضع المختار مضبوطان: حقول الاختبار في وضع الاختبار، والحقول الفعلية في غير ذلك. تعرض صفحة الإعدادات تحذيرًا عند غيابها. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

The payment went through, but no order was created: من المرجح أن عنوان الإشعار الفوري غير مضبوط لحساب DPO الخاص بك، ولم يعد العميل إلى المتجر. اطلب من دعم DPO ضبط العنوان المعروض في الإعدادات، وتحقق من أن cron يستدعي عنوان الفحص كل 15 دقيقة. فعّل Logging وراجع حقل Log في صفحة الوحدة.

Push notification answers Unknown transaction: رمز المعاملة لا ينتمي إلى دفعة DPO Pay لهذا المتجر، مثلًا عندما يأتي الإشعار من متجر آخر على الحساب نفسه لدى DPO.

Push notification answers Verification failed: تعذّر الوصول إلى DPO للتحقق من الدفعة، أو كانت السلة تُعالَج بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). تكرر DPO الإشعار، ويؤكد الفحص المجدول الطلب أيضًا. السبب موجود في السجل.

The push URL shows Method not allowed in the browser: هذا طبيعي. يقبل العنوان الطلبات الصادرة من DPO فقط.

The cron URL answers Forbidden: الرمز في العنوان غير صحيح. انسخ العنوان مرة أخرى من صفحة Configure. يجيب الاستدعاء الصحيح بـ OK checked= وعدد الدفعات التي جرى فحصها.

The Service Type is not saved: يجب أن يكون Service Type ID رقميًا من DPO.

The customer sees DPO Pay is temporarily unavailable: رفضت DPO إنشاء المعاملة، مثلًا بسبب Company Token أو Service Type غير صحيح، أو بسبب رمز من الوضع الآخر. رمز نتيجة DPO موجود في السجل.

The customer sees that DPO accepts at most 2 decimal places: إجمالي السلة له ثلاث منازل عشرية. لا تستطيع DPO تحصيل هذه المبالغ.

The customer sees This order has already been paid with DPO Pay: رفضت DPO دفعة ثانية للسلة نفسها. تحقق من الدفعة في بوابة DPO ومن الطلب في PrestaShop.

Order is DPO payment on hold after payment: اقرأ الملاحظة الخاصة في صفحة الطلب (انظر حالات الطلب)، ثم راجع المعاملة في بوابة DPO.

يمكن للمطورين تغيير بيانات العميل المرسلة إلى DPO عبر الخطاف actionWcpDpoPayCustomerData، وتغيير المهلة المحددة للدفع عبر actionWcpDpoPayPaymentTimeLimit.

الإلغاء

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

DPO Pay علامة تجارية تعود ملكيتها إلى مالكها. هذه الوحدة غير تابعة لـ DPO Pay ولا تحظى بتأييدها.