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

المتطلبات

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

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

حساب التاجر لدى iPay88: يصدر iPay88 كلًا من Merchant Code وMerchant Key عند تفعيل حساب التاجر الخاص بك. وتظهران أيضًا في بوابة التاجر لدى iPay88. إذا لم تكن تاجرًا بعد، فقدّم طلبًا على موقع iPay88. احتفظ بمفتاح Merchant Key سريًا: فهو يوقّع المدفوعات. لا يملك iPay88 بيئة اختبار (sandbox) منفصلة، لذلك لا توجد مفاتيح اختبار.

عنوان Request URL: يجب تسجيل عنوان موقعك لدى iPay88 كعنوان Request URL. وإلا ستعرض صفحة iPay88 الرسالة "Permission not allow".

العملة: Malaysia — MYR، وUSD أو SGD أو AUD أو CAD أو EUR أو GBP أو HKD أو CNY أو TWD أو INR أو IDR أو PHP أو THB إذا كان خيار تعدد العملات مفعّلًا في حساب iPay88 الخاص بك؛ وPhilippines — PHP أو USD؛ وIndonesia — IDR؛ وThailand — THB. إذا تعذّر خصم عملة السلة في منطقتك، تُخفى طريقة الدفع عند الدفع.

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

التثبيت

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

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

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

4. اختر iPay88 region الخاص بك، وأدخل Merchant Code وMerchant Key، وفعّل Enable/Disable، ثم انقر على Save.

5. للتحقق من الإعداد، أجرِ دفعة مع تفعيل Test mode، ثم أوقف وضع الاختبار.

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

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox iPay88 Payment > Configure. يحفظ كل زر Save الصفحة بأكملها. وتعرض الصفحة فوق الحقول الرسالة أدخل Merchant Code وMerchant Key الخاصين بـ iPay88 — حتى ذلك الحين لن تظهر طريقة الدفع عند الدفع. طالما كان مفتاح مفقودًا، وتحذيرًا عندما لا يمكن خصم العملة الافتراضية للمتجر في المنطقة المختارة (عندها تُخفى طريقة الدفع عند الدفع)، وتحذيرًا طالما كان وضع الاختبار مفعّلًا.

iPay88

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via iPay88 (credit card, online banking, e-wallet).

حساب iPay88

iPay88 region: دولة حساب التاجر لديك في iPay88. وهي تحدد صفحة الدفع الخاصة بـ iPay88 والعملات القابلة للخصم. يُخصم الطلب دائمًا بعملته الخاصة. الافتراضي: Malaysia.

Merchant Code: رمز التاجر الخاص بك لدى iPay88، مثل M01234.

Merchant Key: مفتاح التاجر الخاص بك لدى iPay88. يوقّع طلبات الدفع ويتحقق من ردود iPay88. احتفظ به سريًا. لا يُعرض المفتاح المحفوظ مرة أخرى: يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للاحتفاظ به. أدخل قيمة جديدة فقط إذا أردت تغييره. يُحفظ المفتاح كما أدخلته تمامًا، بما في ذلك علامات الاقتباس والشرطات المائلة العكسية.

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

Signature type: طريقة توقيع طلبات الدفع. تُتحقق الردود بالصيغتين، لذلك تظل المدفوعات التي بدأت قبل التبديل قابلة للتحقق.

الدفع

Payment method: اختر مسبقًا طريقة دفع واحدة من iPay88 من قائمة PaymentId الخاصة بـ Malaysia، أو اترك Let the customer choose on the iPay88 page (الافتراضي). تشمل القائمة Credit Card (MYR) وFPX (Online Banking) وMaybank2U وAlliance Online وAmBank وRHB Bank وHong Leong Bank وCIMB Clicks وWeb Cash وPayPal (MYR) وCredit Card (PHP) وBoost وTouch n Go eWallet وGrabPay وShopeePay.

Reference prefix: اختياري. يُضاف قبل رقم السلة في مرجع iPay88 (RefNo)، مثل SHOP1-. اضبط بادئة مختلفة في كل متجر يستخدم حساب iPay88 نفسه، حتى لا يُطبَّق رد متجر على سلة متجر آخر أبدًا. الأحرف والأرقام و"-" و"_"، بحد أقصى 10 أحرف. تُحذف الأحرف الأخرى عند الحفظ، وتُضاف "-" في نهاية البادئة إذا انتهت برقم، لأن رقم السلة يُقرأ من نهاية RefNo. تعرض الصفحة بعد ذلك القيمة المحفوظة. إذا انتقلت من WooCommerce إلى PrestaShop بحساب iPay88 نفسه، فاضبط بادئة حتى لا تكرر المراجع الجديدة أرقام الطلبات القديمة أبدًا.

Test mode: Charge a fixed test amount instead of the order total. لا يملك iPay88 بيئة اختبار منفصلة: مدفوعات الاختبار معاملات حقيقية في صفحة iPay88 الفعلية بمبلغ صغير (1.00؛ IDR 10,000). يُعلَّم الطلب كمدفوع عند استلام مبلغ الاختبار، وتذكر ملاحظة الطلب ذلك. وطالما كان وضع الاختبار مفعّلًا، يعرض الدفع الرسالة TEST MODE: only a test amount of ... will be charged. تُقارن الدفعة التي بدأت في وضع الاختبار دائمًا بمبلغ الاختبار، حتى لو أوقفت وضع الاختبار قبل أن يردّ iPay88. لا تُبقِ وضع الاختبار مفعّلًا أبدًا في متجر فعلي. الافتراضي: معطّل.

عنوانا الرد وbackend

ترسل الوحدة العنوانين مع كل دفعة، لذلك لا يلزم إعداد أي شيء. إذا طلبهما iPay88، فانسخهما من هذا القسم. وبعناوين ودية تبدو هكذا: https://your-shop/module/wcp_ipay88_payment/response (Response URL، عودة العميل) وhttps://your-shop/module/wcp_ipay88_payment/backend (Backend URL، الإشعار من الخادم إلى الخادم)، وقد يتضمن رمز لغة مثل /en/. ويعرض القسم أيضًا عنوان موقعك، الذي يجب تسجيله لدى iPay88 كعنوان Request URL.

تُتحقق الردّان من iPay88 بالطريقة نفسها: الحقول المطلوبة، والتوقيع الذي أُنشئ بمفتاح Merchant Key الخاص بك، ومرجع الدفعة التي بدأها هذا المتجر لهذه السلة. الردود التي لا تحمل توقيعًا صالحًا تُرفض ولا تغيّر السلة أو الطلب أبدًا. ولا يتلقى إشعار backend الرد RECEIVEOK إلا بعد معالجته، وإلا أعاد iPay88 إرساله. ويعمل حتى عندما يكون المتجر في وضع الصيانة، ولا يتأثر بقيود الدول المفروضة على متجرك. يُبلغ iPay88 حالات الدفع التالية:

متقدم

Debug log: يسجّل طلبات الدفع وردود iPay88 في logs/ipay88_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا يُسجَّل أي بيانات شخصية أو Merchant Key أو توقيعات. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون المفتاح معطّلًا. الافتراضي: معطّل.

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

Delete data on uninstall: يحذف الإعدادات والسجلات وبيانات دفع iPay88 عند إلغاء تثبيت الوحدة. لا تُحذف الطلبات وحالات الطلب أبدًا. الافتراضي: معطّل.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا iPay88) ويؤكد. وتعرض الصفحة التالية Redirecting to iPay88 payment gateway... وPlease do not close this window. أثناء إرسال نموذج إلى صفحة الدفع الخاصة بـ iPay88 في منطقتك. بدون JavaScript ينقر العميل على Pay Now. لا يوجد طلب في هذه المرحلة بعد. تمرر الوحدة إجمالي السلة بعملة السلة (مبلغ الاختبار في وضع الاختبار)، وأسماء المنتجات، واسم العميل وبريده الإلكتروني وهاتفه. وفي صفحة iPay88 يدفع العميل ببطاقة أو عبر FPX للخدمات المصرفية الإلكترونية أو محفظة إلكترونية أو بأي وسيلة أخرى يتيحها حسابك.

لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكده iPay88 بردّ موقَّع، سواء عند عودة العميل أو عبر إشعار backend. وبعد دفعة ناجحة يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب المعتادة مع الرسالة Your iPay88 payment has been received. وللدفعة المعلّقة تعرض الصفحة Your payment is pending confirmation from iPay88. We will update your order as soon as the payment is confirmed. وللطلب في حالة الانتظار تعرض We have received a payment notification from iPay88 and are reviewing it. We will contact you if anything is needed. وإذا كان الطلب في حالة Payment error أو أُلغي، تعرض The payment was not completed. Please contact us.

إذا كان التأكيد يُعالَج في الوقت نفسه بواسطة إشعار backend، يرى العميل الرسالة We have not received the payment confirmation from iPay88 yet. If you completed the payment, your order will be updated shortly. مع الزرين Check again وBack to checkout.

إذا فشلت الدفعة أو أُلغيت، فلا يُنشأ أي طلب وتُحفظ السلة. يعود العميل إلى صفحة الدفع مع الرسالة The payment was not completed: والسبب الذي أبلغ به iPay88، يتبعها You can try again or choose another payment method. يستخدم كل محاولة للسلة نفسها المرجع RefNo ذاته. وإذا تعذّر التحقق من الرد، يرى العميل الرسالة The payment response could not be verified. If you completed the payment, please contact us with your order number — the payment will be checked manually. مع زر Return to the store.

إذا تعذّر بدء الدفعة، يعود العميل إلى صفحة الدفع مع الرسالة This payment method is temporarily unavailable. Please choose another payment method. (المفاتيح مفقودة أو الإجمالي صفر) أو iPay88 cannot accept payments in ... Please choose another payment method. (العملة غير قابلة للخصم في المنطقة). وإذا كان للسلة طلب بالفعل (مدفوع أو في انتظار دفعة معلّقة)، فلا يُنشأ نموذج دفع ثانٍ ويُنقل العميل إلى صفحة تأكيد الطلب.

تقبل الوحدة المدفوعات لمرة واحدة فقط. لا تتضمن استردادًا من PrestaShop، ولا بطاقات محفوظة، ولا اشتراكات، ولا تفويضًا مسبقًا وتحصيلًا، ولا حقول بطاقة في موقعك. ولا تعيد الاستعلام من iPay88 عن حالة الدفع: تُحدَّث الطلبات فقط من رد iPay88 وإشعار backend.

الطلبات

Order statuses

No order yet: أُرسل العميل إلى iPay88 ولم تصل أي نتيجة بعد، أو فشلت الدفعة. لا يوجد إلا السلة.

Payment accepted: أبلغ iPay88 عن دفعة ناجحة بالمبلغ والعملة المتوقعين. تُسجَّل الدفعة بمعرّف iPay88 TransId بوصفه معرّف المعاملة. تعرض ملاحظة خاصة TransID وPaymentID والمبلغ والعملة. وفي وضع الاختبار تذكر ملاحظة ثانية أن مبلغ الاختبار خُصم بدلًا من إجمالي الطلب.

Awaiting iPay88 payment: أبلغ iPay88 عن الدفعة بوصفها معلّقة. ينتقل الطلب إلى Payment accepted عندما يؤكدها iPay88، أو إلى Payment error إذا فشلت.

Payment error: فشلت دفعة معلّقة لاحقًا. تعرض الملاحظة سبب iPay88. لهذه السلة طلب بالفعل، لذلك لا يستطيع العميل دفعه مرة أخرى، بل يقدّم طلبًا جديدًا.

iPay88 payment on hold: أبلغ iPay88 عن دفعة ناجحة بمبلغ أو عملة تختلف عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. لم يُعلَّم الطلب كمدفوع. وتشرح الملاحظة ذلك. تحقّق من الدفعة في بوابة iPay88، ثم أكمل الطلب أو استرد الدفعة.

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

كتلة الدفع في iPay88

تعرض صفحة الطلب كتلة iPay88 payment تتضمن RefNo وTransId والحالة والمبلغ المطلوب والمبلغ المستلم وPaymentId وAuthCode والخطأ والمنطقة، وشارة TEST MODE للدفعات التجريبية.

الاستردادات

لا تُرسل الاستردادات من PrestaShop إلى iPay88. استرد الدفعة في بوابة التاجر لدى iPay88، ثم سجّل الاسترداد في PrestaShop يدويًا.

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

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

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

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

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

لا يظهر iPay88 عند الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Merchant Code وMerchant Key مُدخلان، وأن عملة السلة قابلة للخصم في iPay88 region المختار. تعرض صفحة الإعدادات تحذيرًا عند غياب شيء ما. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: لم يصل إلى متجرك أي من عودة العميل أو إشعار backend بتوقيع صالح. راجع حقل Log: تُسجَّل الأخطاء دائمًا. تحقّق من أن Merchant Key هو المفتاح نفسه الذي أعطاك إياه iPay88 تمامًا، وأن خادمك يقبل طلبات iPay88 على عنوان Backend URL المعروض في الإعدادات.

تعرض صفحة iPay88 الرسالة "Permission not allow": عنوان موقعك غير مسجّل لدى iPay88 كعنوان Request URL. اطلب من iPay88 تسجيل العنوان المعروض في قسم Response and backend URLs.

يردّ إشعار backend بالرسالة BAD SIGNATURE: التوقيع لا يطابق Merchant Key. تحقّق من Merchant Key. لم يتغير شيء.

يردّ إشعار backend بالرسالة NOT CONFIGURED: لم يُضبط Merchant Code أو Merchant Key، لذلك لا يمكن التحقق من الرد. سيعيد iPay88 إرسال الإشعار.

يردّ إشعار backend بالرسالة UNKNOWN ORDER: لم تُبدأ أي دفعة لـ iPay88 بهذا المرجع في هذا المتجر، مثلًا لأن متجرًا آخر على الحساب نفسه لا يستخدم Reference prefix أو يستخدم البادئة نفسها، أو لأن بيانات دفع iPay88 حُذفت عند إلغاء التثبيت.

يردّ إشعار backend بالرسالة RETRY: كانت السلة تُؤكَّد في الوقت نفسه بعودة العميل، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). سيعيد iPay88 إرسال الإشعار.

يعرض عنوان Backend URL الرسالة BAD REQUEST في المتصفح: هذا طبيعي. لا يقبل العنوان إلا الطلبات الموقّعة من iPay88.

الطلب في حالة iPay88 payment on hold: أبلغ iPay88 عن دفعة لا تطابق الطلب، أو كان الطلب قد أُلغي. راجع ملاحظة الطلب والدفعة في بوابة iPay88، ثم أكمل الطلب أو استرد الدفعة.

يرى العميل الرسالة "iPay88 cannot accept payments in" مع اسم عملة: عملة السلة لا يمكن خصمها في المنطقة المختارة. وفي iPay88 Malaysia، تحتاج العملات غير MYR أيضًا إلى خيار تعدد العملات في حسابك لدى iPay88.

يُخصم من العملاء الفعليين 1.00 فقط: Test mode مفعّل. أوقفه.

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

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

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