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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

حساب Quickpay: تحتاج إلى قيمتين من مدير Quickpay: مفتاح API لمستخدم API (لإنشاء المدفوعات وتحصيلها واستردادها)، والمفتاح الخاص بالحساب (للتحقق من توقيع استدعاءات Quickpay). لا يلزم إعداد أي شيء آخر في Quickpay. يجب أن يكون متجرك متاحًا من الإنترنت، وغير محمي بكلمة مرور، حتى تصل استدعاءات Quickpay.

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

التثبيت

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

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

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

4. الصق مفتاح API والمفتاح الخاص من مدير Quickpay، ثم انقر على Test API key (انظر الإعدادات).

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. إلى أن يُحفظ مفتاح API والمفتاح الخاص معًا، تعرض الصفحة الرسالة Quickpay يحتاج إلى إعداد: أدخل مفتاح API والمفتاح الخاص. إلى أن يُحفظا معًا يكون طريقة الدفع مخفية عند الدفع. وبينما Test payments مفعّل، تذكّرك الصفحة بإيقافه عندما يصبح حساب Quickpay مباشرًا.

Quickpay

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely by card or MobilePay on the Quickpay payment page.

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

في مدير Quickpay (manage.quickpay.net) افتح Settings > Integration. انسخ مفتاح API لمستخدم API (Settings > Users) والمفتاح الخاص بالحساب.

Callback URL: يعرض عنوان URL لرد الاتصال في متجرك. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_quickpay_gateway/callback. يستدعيه Quickpay بعد كل عملية دفع (التفويض، التحصيل، الاسترداد، الإلغاء). يُرسل تلقائيًا مع كل دفعة، لذلك لا يلزم إعداد أي شيء في Quickpay.

API key: مفتاح API لمستخدم API في Quickpay. يُستخدم لإنشاء المدفوعات وتحصيلها واستردادها.

Private key: المفتاح الخاص بالحساب. يُستخدم للتحقق من توقيع (HMAC-SHA256) استدعاءات Quickpay. بدونه لا يمكن تأكيد أي دفعة، وتُرفض الاستدعاءات.

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

مسح الأسرار المحفوظة: ضع علامة على API key أو Private key وانقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

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

Test API key: يتحقق هذا الزر من المفتاح المكتوب في حقل API key (أو المحفوظ إن كان الحقل فارغًا) بطلب موثّق إلى Quickpay، دون حفظه. وتكون الإجابات: نجح الاتصال — مفتاح API صالح.، رفض Quickpay مفتاح API.، مفتاح API غير مُعدّ.، أو فشل الاتصال: متبوعًا بالسبب.

الدفع

Capture: الوقت الذي يُخصم فيه المبلغ من البطاقة.

Order status after payment: حالة الطلب بعد أن يؤكد Quickpay الدفعة المحصّلة.

متقدم

Debug log: يكتب في logs/qpg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات، مثل الاستدعاءات المرفوضة وأخطاء Quickpay API، دائمًا. فعّله لتسجيل تفاصيل كل طلب واستدعاء أيضًا. لا تُسجَّل مفاتيح API ولا بيانات البطاقات ولا بيانات العملاء أبدًا. الافتراضي: معطّل.

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

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

الدفع

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

بعد الدفع يعود العميل إلى متجرك. العودة في حد ذاتها لا تُعلِّم أي شيء كمدفوع. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Quickpay: ينشئ الاستدعاء الموقَّع الطلب عندما يتطابق المبلغ المحصّل والعملة مع السلة. ثم يرى العميل صفحة تأكيد الطلب القياسية. مع Authorize only يُنشأ الطلب في Quickpay payment on hold بدلًا من ذلك، وتحصّل الدفعة لاحقًا. وإذا لم يصل الاستدعاء بعد عند عودة العميل، تعرض صفحة Payment confirmation الرسالة يقوم Quickpay بتأكيد دفعتك. ستتلقى بريدًا إلكترونيًا فور تأكيد الطلب. مع الزرين Check again وBack to checkout.

إذا ألغى العميل في نافذة الدفع، يُحذف رابط الدفع في Quickpay ويعود العميل إلى صفحة الدفع مع الرسالة تم إلغاء الدفع. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وإذا رُفضت البطاقة، فالرسالة هي لم يكتمل الدفع. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. تُحفظ السلة. تعيد المحاولة الجديدة استخدام دفعة Quickpay الخاصة بالسلة مع رابط جديد، لذلك لا يمكن دفع الرابط القديم بالتوازي أبدًا. وبينما تكون دفعة من السلة مفوّضة وتنتظر التحصيل، لا تبدأ دفعة ثانية؛ ويرى العميل صفحة Payment confirmation.

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

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

تقبل الوحدة المدفوعات لمرة واحدة فقط. لا تتضمن اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة، ولا تحصيلًا جزئيًا، ولا ترسل بنود السلة أو الفاتورة إلى Quickpay، ولا تتضمن طرق MobilePay أو Apple Pay أو Klarna منفصلة: يختار العميل من بين الطرق الموجودة في نافذة دفع Quickpay لديك.

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

حالات الطلب

No order yet: أُرسل العميل إلى Quickpay ولم يدفع، أو رُفضت البطاقة، أو الدفعة مفوّضة وتنتظر التحصيل التلقائي. توجد السلة فقط.

Payment accepted or Delivered: أكّد Quickpay الدفعة المحصّلة بالمبلغ والعملة الصحيحين. تتبع الحالة Order status after payment. تُسجَّل الدفعة بمعرّف دفع Quickpay كمعرّف للمعاملة، وتعرض ملاحظة الدفعة (ومعلَّمة TEST في مدفوعات الاختبار).

Quickpay payment on hold: الدفعة مفوّضة فقط وتنتظر Capture Quickpay payment؛ أو أبلغ Quickpay عن مبلغ أو عملة تختلف عن إجمالي الطلب (مثلًا: تغيّرت السلة بعد بدء الدفع، أو حُصّل مبلغ مختلف في مدير Quickpay)؛ أو فشل التحصيل التلقائي وما زال المبلغ محجوزًا فقط. تشرح الملاحظة السبب. وعند تحصيل مال بمبلغ مختلف، تُسجَّل الدفعة في الطلب بالمبلغ الذي حصّله Quickpay.

Canceled: ألغيت الطلب، أو أُلغيت دفعة طلب معلّق في مدير Quickpay.

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

لا تغيّر الدفعة الواردة لطلب مدفوع أو ملغى أو مُسترَد الطلب. وتطلب منك ملاحظة التحقق من الدفعة في مدير Quickpay، مثلًا لاسترداد دفعة مكررة.

عند إلغاء طلب غير مدفوع يُحذف رابط دفعه في Quickpay. أما إلغاء طلب مفوّض فلا يحرر المبلغ المحجوز تلقائيًا: تذكّرك ملاحظة بإلغاء الدفعة في مدير Quickpay؛ وإلا ينتهي الحجز عند انتهاء صلاحية التفويض.

كتلة Quickpay

تعرض صفحة الطلب كتلة Quickpay payment تتضمن معرّف الدفع، وحالة الدفع، والمبلغ والمبلغ المسترد، وشارة Test payment لمدفوعات الاختبار، وقائمة بجميع مدفوعات Quickpay الخاصة بالسلة (عندما توجد أكثر من واحدة)، وسجل الاستردادات، وQuickpay notes الخاصة بالطلب. يتطلب التحصيل والاسترداد صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات الوحدات.

التحصيل

مع Authorize only، انقر على Capture Quickpay payment في كتلة Quickpay وأكّد هل تريد تحصيل إجمالي الطلب عبر Quickpay؟ يُحصَّل إجمالي الطلب؛ التحصيل الجزئي غير متاح. إذا أكّد Quickpay فورًا، تُعيَّن حالة الطلب إلى Order status after payment. وإلا تشير ملاحظة إلى أن طلب التحصيل أُرسل، ويُعلَّم الطلب كمدفوع عندما يؤكد استدعاء Quickpay ذلك. ويُعرض التحصيل المرفوض في الكتلة ويُدوَّن في الطلب.

الاستردادات

في كتلة Quickpay أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب السبب اختياريًا، ثم انقر على Refund via Quickpay. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Quickpay؟ لا يمكن التراجع عن هذا الإجراء. الاستردادات الكاملة والجزئية مدعومة للدفعات المحصّلة. تتم الاستردادات بالمبلغ والعملة اللذين حصّلهما Quickpay، لذلك بعد وجود فرق في المبلغ أو العملة يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. يعالج Quickpay الاستردادات بشكل غير متزامن: يعرض سجل الاستردادات requested، ويغيّرها الاستدعاء إلى confirmed أو failed ويضيف النتيجة إلى الملاحظات. إذا رفض Quickpay الاسترداد فورًا، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. يضع الاسترداد الكامل الطلب على Refunded؛ ولا يغيّر الاسترداد الجزئي الحالة. ولا يمكن استرداد دفعة مفوّضة لم تُحصَّل قط؛ ألغِها في مدير Quickpay.

لا تُنشئ الوحدة إشعارات دائنة (credit slips). أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا ترسل المال عبر Quickpay.

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

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

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

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

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

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

لا يظهر Quickpay عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن API key وPrivate key محفوظان. بدون المفتاحين تُخفى طريقة الدفع. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: لم يصل استدعاء Quickpay إلى متجرك أو رُفض. تحقق من أن متجرك متاح من الإنترنت (دون حماية بكلمة مرور)، وأن Private key هو المفتاح الخاص بالحساب نفسه في Quickpay. تُكتب الاستدعاءات المرفوضة دائمًا في السجل الموجود في صفحة الوحدة. فعّل Debug log لرؤية كل استدعاء.

يعرض السجل Callback rejected: invalid checksum.: المفتاح الخاص في الإعدادات لا يخص الحساب الذي أرسل الاستدعاء. انسخه من جديد من Settings > Integration في مدير Quickpay.

يعرض السجل Callback rejected: the private key is not configured.: أدخل المفتاح الخاص. لا تُقبل الاستدعاءات بدونه أبدًا.

يعرض السجل Callback: no cart found for payment …: الاستدعاء يخص دفعة Quickpay لم ينشئها هذا المتجر، مثلًا دفعة تمت خارج PrestaShop.

يعرض السجل Could not lock the cart أو Cannot create the order: كان استدعاء آخر لنفس السلة يُطبَّق في تلك اللحظة، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). يُرد على الاستدعاء بخطأ، لذلك يعيد Quickpay إرساله.

لم تُعلِّم دفعة الاختبار الطلب كمدفوع: Test payments معطّل. يذكر السجل (والملاحظة إن وُجد الطلب) أن دفعة الاختبار لم تُقبل. فعّله أثناء الاختبار، وأوقفه عندما يصبح حسابك مباشرًا.

الطلب في حالة Quickpay payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Quickpay. قد تكون الدفعة مفوّضة فقط وتنتظر Capture Quickpay payment، أو قد يختلف المبلغ أو العملة المدفوعان عن الطلب، أو فشل التحصيل. حصّل الدفعة، أو جهّز الطلب، أو استرد الدفعة.

يقول Test API key «رفض Quickpay مفتاح API.»: المفتاح خاطئ أو يخص مستخدمًا بلا صلاحية API. انسخ مفتاح API لمستخدم API من مدير Quickpay.

يرى العميل «تعذّر بدء دفعة Quickpay.»: انظر إلى حقل Log في صفحة الوحدة. يعرض خطأ Quickpay، مثل عملة لا يقبلها حساب Quickpay لديك.

يفشل الاسترداد: يجب أن يكون للطلب دفعة Quickpay محصّلة. الرسالة لم تُحصَّل دفعة Quickpay لهذا الطلب — لا يوجد ما يمكن استرداده. تعني أن الدفعة مفوّضة فقط؛ حصّلها أو ألغِها في مدير Quickpay. ومبلغ استرداد غير صالح: الحد الأقصى … تعني أن المبلغ أكبر مما تبقى من الدفعة المحصّلة.

يمكن للمطوّرين تغيير معاملات رابط الدفع في Quickpay باستخدام الخطاف actionQpgQuickpayLinkData.

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

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

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