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

المتطلبات

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

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

العملة: AUD أو BAM أو BHD أو CAD أو CHF أو CZK أو DKK أو EUR أو GBP أو HRK أو HUF أو ISK أو MKD أو NOK أو PLN أو RON أو RSD أو RUB أو SEK أو USD. وفي أي عملة أخرى للسلة تُخفى طريقة الدفع عند الدفع. تُرسل المبالغ برقمين عشريين؛ ويُرفض الإجمالي الذي يحتوي على أرقام عشرية أكثر (على سبيل المثال في متجر أسعاره بالدينار البحريني BHD ذات 3 أرقام عشرية) بدلًا من تقريبه.

حساب CorvusPay: تحتاج إلى حساب تاجر لدى CorvusPay. تصدر CorvusPay Store ID وSecret Key لكل متجر، بشكل منفصل للمتجر الاختباري والمتجر الفعلي؛ وتظهر هذه القيم في CorvusPay Merchant Center. يجب إدخال Success URL وCancel URL الخاصين بالوحدة هناك (انظر الإعداد).

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

التثبيت

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

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

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

4. أدخل Store ID وSecret Key لمتجر CorvusPay الاختباري (وكذلك لمتجر الإنتاج للمدفوعات الفعلية). انسخ Success URL وCancel URL الظاهرين في صفحة Configure إلى CorvusPay Merchant Center، للمتجر الاختباري ولمتجر الإنتاج.

5. فعّل Enable/Disable وانقر على Save. أجرِ طلبًا تجريبيًا، ثم أوقف Test Mode للانتقال إلى الوضع الفعلي.

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

الإعداد

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox CorvusPay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تعرض الصفحة الرسالة وضع الاختبار مفعّل. تذهب المدفوعات إلى بيئة الاختبار الخاصة بـ CorvusPay — لا يُخصم أي مبلغ حقيقي. طالما وضع الاختبار مفعّل، وتحذّرك عندما تكون البوابة مفعّلة لكن Store ID أو Secret Key للوضع الحالي فارغ (وعندها تُخفى البوابة عند الدفع حتى يتم ملؤهما)، وعندما لا تكون العملة الافتراضية لمتجرك مدعومة من CorvusPay.

CorvusPay

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit/Debit Card (CorvusPay).

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely with your credit or debit card via CorvusPay. وفي وضع الاختبار تُضاف إليه العبارة (وضع الاختبار — لا يُخصم أي دفع حقيقي.).

بيانات اعتماد المتجر

تصدر CorvusPay Store ID وSecret Key لكل متجر (الاختباري والفعلي بشكل منفصل)، وتظهر هذه القيم في CorvusPay Merchant Center.

Test Mode: يستخدم بيئة الاختبار الخاصة بـ CorvusPay (wallet.test.corvuspay.com) وStore ID وSecret Key الاختباريين. الافتراضي: مفعّل. أوقفه لاستقبال المدفوعات الحقيقية على wallet.corvuspay.com.

Test Store ID: Store ID الرقمي لمتجر CorvusPay الاختباري الخاص بك.

Test Secret Key: Secret Key لمتجر CorvusPay الاختباري الخاص بك، ويُستخدم لتوقيعات HMAC-SHA256.

Live Store ID: Store ID الرقمي لمتجر CorvusPay الفعلي (الإنتاج) الخاص بك.

Live Secret Key: Secret Key لمتجر CorvusPay الفعلي (الإنتاج) الخاص بك، ويُستخدم لتوقيعات HMAC-SHA256.

Clear saved secrets: حدّد Test Secret Key أو Live Secret Key ثم انقر على Save لحذفه.

يجب أن يحتوي Store ID على أرقام فقط. وإذا أدخلت غير ذلك، تعرض الصفحة الرسالة … يجب أن يحتوي على أرقام فقط — تم الاحتفاظ بالقيمة السابقة. وتُحفظ الحقول الأخرى مع ذلك. ولا تُعرض Secret Key المحفوظة مرة أخرى: يبقى الحقل فارغًا وتظهر فيه الرسالة محفوظ — اتركه فارغًا للإبقاء عليه. أدخل قيمة جديدة فقط عندما ترغب في تغييرها. ويُتحقق من كل دفعة دائمًا بـ Secret Key للمتجر الذي بدأت فيه، لذا أبقِ مفتاح الاختبار مملوءًا طالما ما زالت مدفوعات الاختبار قد تعود.

Success URL وCancel URL

انسخ العنوانين الظاهرين في هذا القسم إلى CorvusPay Merchant Center، للمتجر الاختباري ولمتجر الإنتاج. تعيد CorvusPay العميل إليهما بعد الدفع. انسخهما تمامًا كما تعرضهما الصفحة؛ فمع الروابط المهيأة تبدو مثل الأمثلة أدناه، وربما مع رمز لغة مثل /en/.

Success URL: يبدو هكذا: https://your-shop/module/wcp_corvuspay_gateway/success. توقّع CorvusPay هذا الطلب؛ ولا يُنشأ الطلب إلا بعد التحقق من التوقيع.

Cancel URL: يبدو هكذا: https://your-shop/module/wcp_corvuspay_gateway/cancel. لا توقّع CorvusPay هذا الطلب، لذلك لا يمكنه إلا وضع علامة إلغاء على محاولة دفع غير مكتملة برقم طلب CorvusPay أصدره هذا المتجر.

الدفع

Transaction Type: طريقة خصم المبلغ من البطاقة.

Sale (capture immediately): يُخصم المبلغ من البطاقة فورًا (الافتراضي).

Authorize only (capture in Merchant Center): يُحجز المبلغ فقط. يُوضع الطلب في CorvusPay payment on hold؛ وتقوم بتحصيل (إتمام) الدفعة في CorvusPay Merchant Center، ثم تضبط الطلب على Payment accepted.

Payment Page Language: لغة صفحة الدفع في CorvusPay. يستخدم Site language (الافتراضي) اللغة الحالية لمتجرك عندما تدعمها CorvusPay، وإلا فالإنجليزية. ويمكنك أيضًا اختيار Hrvatski أو English أو Deutsch أو Italiano أو Srpski أو Slovenščina.

Order Status After Payment: حالة الطلب بعد دفعة Sale ناجحة. يُنشأ الطلب مباشرة بهذه الحالة.

Payment accepted (default): حالة PrestaShop القياسية للطلبات المدفوعة.

Delivered (completed): يصبح كل طلب مدفوع بحالة Delivered.

CorvusPay payment on hold: ينتظر كل طلب مدفوع مراجعتك اليدوية. وتبقى الدفعة مسجلة على الطلب.

متقدم

Logging: يكتب معلومات التصحيح في logs/corvuspay_p_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. وتُسجَّل الأخطاء دائمًا حتى عندما يكون هذا الخيار متوقفًا؛ أما الأسرار والتوقيعات وبيانات العملاء فلا تُسجَّل أبدًا. الافتراضي: إيقاف.

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

Delete Data: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وملفات السجل. أما الطلبات وبيانات معاملات CorvusPay وحالة الطلب فتُحفظ دائمًا. الافتراضي: إيقاف.

إتمام الشراء

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (CorvusPay)) ويؤكد. تعرض الصفحة التالية جارٍ التحويل إلى CorvusPay للدفع. يرجى الانتظار... وترسل النموذج الموقَّع إلى صفحة الدفع في CorvusPay. إذا لم يبدأ التحويل، ينقر العميل على Pay via CorvusPay؛ ويعيد Back to checkout إلى صفحة الدفع. ويُرسَل إجمالي السلة والعملة ووصف قصير (رقم السلة واسم المتجر) وبيانات عنوان الفوترة والبريد الإلكتروني (لملء صفحة الدفع مسبقًا). لا يوجد طلب بعد في هذه المرحلة. ويُعاد استخدام رقم طلب CorvusPay نفسه ما دام المبلغ والعملة والوضع ونوع المعاملة لم تتغير، ولا تقبل CorvusPay دفعة ثانية له.

بعد الدفع تعيد CorvusPay العميل إلى Success URL. لا تُعلَّم الدفعة كمدفوعة إلا بعد أن تؤكدها CorvusPay: يجب أن يكون رقم طلب CorvusPay صادرًا عن هذا المتجر، ويجب أن يطابق التوقيع Secret Key للمتجر الذي بدأت فيه الدفعة، ويجب أن يطابق المبلغ والعملة السلة. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة تم استلام دفعتك عبر CorvusPay. وبالنسبة إلى Authorize only تعرض الصفحة الرسالة تم تفويض دفعتك عبر CorvusPay. سيُخصم المبلغ عند معالجة المتجر لطلبك.، وبالنسبة إلى طلب في حالة الانتظار الرسالة تم استلام دفعتك وهي قيد المراجعة من المتجر.

إذا تعذّر إنشاء الطلب في تلك اللحظة (مثلًا لأن طلبًا آخر يؤكد السلة نفسها)، يرى العميل الرسالة جارٍ تأكيد دفعتك مع زر Check again، الذي ينقله إلى صفحة تأكيد الطلب فور وجوده. وإذا تعذّر التحقق من طلب Success URL، يرى العميل الرسالة لم يتم تأكيد الدفع والرسالة لم نتمكن من تأكيد هذه الدفعة عبر CorvusPay. إذا خُصم المبلغ من بطاقتك، فيرجى التواصل مع المتجر — ولا تدفع مرة أخرى. ولا يتغير شيء. ويعمل Success URL حتى عندما يكون المتجر في وضع الصيانة.

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

إذا تعذّر بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة: CorvusPay غير مُعَدّ. يرجى اختيار طريقة دفع أخرى.، أو لا تقبل CorvusPay المدفوعات بالعملة …، أو لا يمكن دفع إجمالي هذا الطلب عبر CorvusPay (يجب أن يكون أكبر من الصفر وبحد أقصى رقمين عشريين). يرجى اختيار طريقة دفع أخرى.

لا يُؤكَّد الطلب إلا عندما تعيد CorvusPay العميل إلى Success URL؛ ولا توجد إشعارات من خادم إلى خادم. وإذا أغلق العميل المتصفح مباشرة بعد الدفع، فلن يُنشأ أي طلب. ولا توفر الوحدة عمليات الاسترداد أو التحصيل (capture) أو الإلغاء (void) من PrestaShop (تتطلب واجهة CorvusPay البرمجية من الخادم شهادة عميل)، ولا البطاقات المحفوظة أو الاشتراكات أو الأقساط أو نموذج البطاقة داخل الموقع.

الطلبات

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى CorvusPay ولم يعد بدفعة مؤكدة. لا يوجد سوى السلة. وإذا دفع العميل ولم يعد، فتحقّق من الدفعة في CorvusPay Merchant Center وأنشئ الطلب يدويًا.

Payment accepted أو Delivered أو CorvusPay payment on hold: تم تأكيد دفعة Sale. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة بمعرّف معاملة CorvusPay، أو برقم طلب CorvusPay إذا لم ترسل CorvusPay معرّفًا، ويمكن العثور على الدفعة في Merchant Center بهذا الرقم. وتعرض ملاحظة الطلب الخاصة رقم طلب CorvusPay ورمز الموافقة ونوع البطاقة.

CorvusPay payment on hold, authorized: Authorize only محدّد. حصّل الدفعة في CorvusPay Merchant Center، ثم اضبط الطلب على Payment accepted.

CorvusPay payment on hold, amount/currency mismatch: المبلغ المدفوع أو العملة لا يطابقان السلة، مثلًا لأن السلة عُدّلت في تبويب آخر. تُسجَّل الدفعة بالمبلغ المدفوع فعلًا عندما تكون بعملة الطلب. لا تشحن قبل التحقق من الدفعة في CorvusPay Merchant Center.

CorvusPay payment on hold, payment after cancel: وصلت دفعة ناجحة لمحاولة دفع كان العميل قد ألغاها. نفّذ الطلب أو استرد الدفعة في CorvusPay Merchant Center.

إذا وصلت دفعة ناجحة أخرى مختلفة لسلة لديها طلب بالفعل، فلن يتغير الطلب. وتطلب منك ملاحظة التحقق من CorvusPay Merchant Center واسترداد الدفعة المكررة إذا لزم الأمر.

كتلة دفع CorvusPay

تعرض صفحة الطلب كتلة CorvusPay payment تتضمن رقم طلب CorvusPay وحالة محاولة الدفع ونوع المعاملة (Sale أو Authorize only) والمبلغ (والمبلغ المستلم، إذا أبلغت عنه CorvusPay) ورمز الموافقة والمعاملة ونوع البطاقة. وتُعلَّم المدفوعات التجريبية بعبارة Test.

عمليات الاسترداد: عمليات الاسترداد والتحصيل (capture) والإلغاء (void) من PrestaShop غير مدعومة. نفّذها في CorvusPay Merchant Center وسجّل النتيجة في PrestaShop يدويًا.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox CorvusPay Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox CorvusPay Gateway > Configure، فوق الإعدادات. الصق المفتاح في حقل License key ثم انقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموَّهًا، والحالة (مثل التاريخ الذي تظل فيه الرخصة فعّالة ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: presta-payment-corvuspay ورابط «إدارة التراخيص والنطاقات في حسابك»، الذي يفتح حسابك في vibefox.net. ولا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure للوحدة. وتتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد متعدد المتاجر. ولا تُحرَّر خانة النطاق بإزالة المفتاح من المتجر. حرّر الخانة من حسابك في vibefox.net.

بدون مفتاح نشط لا تظهر CorvusPay للعملاء عند الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل الرسالة طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها في صفحة الدفع. ويظهر تذكير في Modules > Module Manager على تبويب Alerts. ولا تتأثر الطلبات الحالية: تظل الدفعات التي بدأت بالفعل تُؤكَّد عندما يعود العميل من CorvusPay.

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

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

لا تظهر CorvusPay عند الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن Store ID وSecret Key للوضع الحالي مملوءان (Test Store ID وTest Secret Key في وضع الاختبار، وLive Store ID وLive Secret Key في وضع الإنتاج)، وأن عملة السلة مدعومة من CorvusPay. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: من المرجّح أن Success URL غير مُدخَل في CorvusPay Merchant Center، أو أن Secret Key في PrestaShop لا يطابق المتجر. ابحث عن INVALID signature في الحقل Log في صفحة الوحدة (تُسجَّل الأخطاء دائمًا). ولا يُنشأ الطلب أيضًا إذا أغلق العميل المتصفح قبل العودة؛ وعندها تحقّق من الدفعة في Merchant Center وأنشئ الطلب يدويًا.

يرى العميل الرسالة لم يتم تأكيد الدفع: رُفض طلب Success URL: كانت الحقول المطلوبة ناقصة، أو لم يصدر رقم طلب CorvusPay عن هذا المتجر، أو كان Secret Key لذلك المتجر فارغًا، أو لم يطابق التوقيع. لم يتغير شيء. ويعرض السجل السبب.

يرى العميل الرسالة جارٍ تأكيد دفعتك لفترة طويلة: تعذّر إنشاء الطلب، مثلًا لأن الوحدة كانت معطّلة أو لأن السلة لم تعد صالحة. يعرض السجل السبب؛ تحقّق من الدفعة في Merchant Center.

يرى العميل الرسالة لا يمكن دفع إجمالي هذا الطلب عبر CorvusPay: الإجمالي صفر أو يحتوي على أكثر من رقمين عشريين.

يرى العميل الرسالة CorvusPay غير مُعَدّ أو لا تقبل CorvusPay المدفوعات بالعملة …: Store ID أو Secret Key للوضع الحالي مفقود، أو عملة السلة غير مدعومة.

الطلب في حالة CorvusPay payment on hold: اقرأ الملاحظات الخاصة بالطلب. إما أن Authorize only محدّد، أو أن المبلغ أو العملة المدفوعة لم يطابقا السلة، أو أن الدفعة وصلت بعد إلغاء العميل لها، أو أن Order Status After Payment مضبوط على حالة الانتظار.

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

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

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