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

المتطلبات

WordPress: الإصدار 6.0 أو أحدث.

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

PHP: الإصدار 8.0 أو أحدث.

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

2. انقر Activate.

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

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

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

6. فعِّل Enable/Disable، وأنشئ طلبًا تجريبيًا، ثم ألغِ تحديد Test Mode للانتقال إلى الوضع الفعلي.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > CorvusPay. تعرض الصفحة فوق الحقول Test mode is on. ما دام الوضع الاختباري مفعَّلًا، وتحذرك عندما تكون البوابة مفعَّلة لكن Store ID أو Secret Key للوضع الحالي فارغًا (وعندها تُخفى في صفحة الدفع إلى أن يُملأ)، وعندما لا تدعم CorvusPay عملة المتجر.

عام

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

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

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

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

تُصدر CorvusPay كلًّا من Store ID وSecret Key لكل متجر (الاختباري ومتجر الإنتاج بشكل منفصل)، وهما معروضان في CorvusPay Merchant Center.

Test Mode: يستخدم Enable test mode بيئة الاختبار في CorvusPay (wallet.test.corvuspay.com) وStore ID وSecret Key الاختباريين. الافتراضي: مفعَّل.

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.

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

Success URL وCancel URL

انسخ العنوانين المعروضين في هذا القسم إلى CorvusPay Merchant Center، للمتجر الاختباري ولمتجر الإنتاج. تعيد CorvusPay العميل إليهما بعد الدفع.

Success URL: يبدو مثل https://your-site/wc-api/corvuspay_payment_success/. توقّع CorvusPay هذا الطلب؛ ولا يُعلَّم الطلب كمدفوع إلا بعد التحقق من التوقيع.

Cancel URL: يبدو مثل https://your-site/wc-api/corvuspay_payment_cancel/. لا توقّعه CorvusPay، لذا لا يمكنه إلا إلغاء طلب غير مدفوع يحمل رقم طلب CorvusPay صادرًا عن هذا المتجر.

الدفع

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

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

Authorize only (capture in Merchant Center): يُحجز المبلغ فقط. يوضع الطلب قيد الانتظار؛ وتقوم أنت بتحصيل الدفعة (capture) وإكمالها في CorvusPay Merchant Center، ثم تحوّل الطلب إلى قيد المعالجة.

Payment Page Language: لغة صفحة الدفع في CorvusPay. يستخدم Site language (الافتراضي) اللغة الحالية لموقعك إذا كانت CorvusPay تدعمها، وإلا فالإنجليزية. ويمكنك أيضًا اختيار الكرواتية أو الإنجليزية أو الألمانية أو الإيطالية أو الصربية أو السلوفينية.

Order Status After Payment: حالة الطلب بعد نجاح دفعة Sale. تُضبط الحالة فورًا، دون تغيير ثانٍ للحالة.

Processing (WooCommerce default): الافتراضي.

Completed: يصبح كل طلب مدفوع مكتملًا.

On Hold: ينتظر كل طلب مدفوع مراجعتك اليدوية.

متقدم

Logging: يكتب Enable debug logging في WooCommerce > Status > Logs، بالمصدر wcp_corvuspay_gateway. تُسجَّل الأخطاء دائمًا؛ أما الأسرار وبيانات العملاء فلا تُسجَّل أبدًا. الافتراضي: متوقف.

Delete Data: Delete the plugin settings and log files when the plugin is deleted (uninstalled). لا يحذف التعطيل أي شيء أبدًا. وتبقى بيانات الدفع المخزنة في الطلبات دائمًا. الافتراضي: متوقف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (CorvusPay)) ويُنشئ الطلب. يبقى الطلب في حالة في انتظار الدفع، وتعرض صفحة Pay for order الرسالة Redirecting to CorvusPay for payment. Please wait... وترسل النموذج الموقَّع إلى صفحة الدفع في CorvusPay. وإذا لم يبدأ التحويل ينقر العميل Pay via CorvusPay. تُرسَل قيمة الطلب الإجمالية والعملة ووصف موجز للسلة وبيانات الفوترة (لملء صفحة الدفع مسبقًا). ويُعاد استخدام رقم طلب CorvusPay نفسه ما دام المبلغ لم يتغير، ولا تقبل CorvusPay دفعة ثانية له.

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

إذا ألغى العميل الدفع في صفحة CorvusPay يُلغى الطلب غير المدفوع، ويعود العميل إلى صفحة الدفع وسلته كما هي مع الرسالة The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. وإذا بدأت الدفعة من صفحة Pay for order وكانت السلة فارغة، يعرض WooCommerce الرسالة The CorvusPay payment was cancelled and the order was not paid. في صفحة السلة. وإذا تعذر التحقق من طلب Success URL، يرى العميل الرسالة We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. ولا يتغير الطلب.

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

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

الطلبات

حالات الطلبات

Pending payment: حُوِّل العميل إلى CorvusPay ولم يعد بعد. وإذا دفع العميل ولم يعد، فتحقق من الدفعة في CorvusPay Merchant Center وأكمل الطلب يدويًا.

Processing أو Completed أو On Hold: تم تأكيد دفعة Sale. تتبع الحالة إعداد Order Status After Payment. وتعرض ملاحظة الطلب رقم طلب CorvusPay ورمز الموافقة ونوع البطاقة. ومعرّف معاملة الطلب هو معرّف معاملة CorvusPay، أو رقم طلب CorvusPay إذا لم ترسل CorvusPay معرّفًا، ويمكن بواسطته العثور على الدفعة في Merchant Center.

On hold، مفوَّض: تم تحديد Authorize only. حصِّل الدفعة (capture) في CorvusPay Merchant Center، ثم حوّل الطلب إلى قيد المعالجة.

On hold، عدم تطابق المبلغ/العملة: المبلغ أو العملة المدفوعة لا تطابق الطلب. لا تشحن قبل التحقق من الدفعة في CorvusPay Merchant Center.

On hold، دفعة لطلب ملغى: وصلت دفعة ناجحة بعد إلغاء الطلب، مثلًا بسبب انتهاء مهلة الطلبات غير المدفوعة. نفِّذ الطلب أو استردّ الدفعة في CorvusPay Merchant Center.

Cancelled: ألغى العميل الدفع في صفحة CorvusPay.

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

Refunds: لا تُدعم عمليات الاسترداد والتحصيل والإلغاء من WooCommerce. أجرِها في CorvusPay Merchant Center وسجّل الاسترداد في WooCommerce يدويًا.

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

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

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

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

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

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

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

تمت الدفعة لكن الطلب يبقى في انتظار الدفع: على الأرجح أن Success URL غير مُدخَل في CorvusPay Merchant Center، أو أن Secret Key في WooCommerce لا يطابق المتجر. فعِّل Logging وابحث عن INVALID signature في WooCommerce > Status > Logs، بالمصدر wcp_corvuspay_gateway. ويبقى الطلب معلقًا أيضًا إذا أغلق العميل المتصفح قبل العودة؛ وعندها تحقق من الدفعة في Merchant Center وأكمل الطلب يدويًا.

يرى العميل We could not confirm this CorvusPay payment: رُفض طلب Success URL: كانت هناك حقول مطلوبة مفقودة، أو لم يصدر رقم طلب CorvusPay لهذا الطلب، أو أن Secret Key لذلك المتجر فارغ، أو لم يتطابق التوقيع. ولا يتغير الطلب. ويعرض السجل السبب.

يرى العميل This order total cannot be paid via CorvusPay: الإجمالي صفر أو يحتوي على أكثر من منزلتين عشريتين.

يرى العميل CorvusPay is not configured أو CorvusPay does not accept payments in …: Store ID أو Secret Key للوضع الحالي مفقود، أو أن عملة الطلب غير مدعومة.

الطلب في حالة On hold: اقرأ ملاحظة الطلب. إما أن Authorize only محدد، أو أن المبلغ أو العملة المدفوعة لم تطابق الطلب، أو أن الدفعة وصلت بعد إلغاء الطلب.

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

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

تعطيل الإضافة يُبقي جميع البيانات. ولإزالتها، عطّلها ثم احذفها من صفحة Plugins. يُزال دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. أما إعدادات البوابة وملفات السجل فلا تُزال إلا إذا كان Delete Data مفعَّلًا. وإلا فتبقى لإعادة تثبيت لاحقة. وتبقى بيانات الدفع المخزنة في الطلبات دائمًا. وتحتفظ الطلبات القائمة بملاحظات الدفع ومعرّفات المعاملات.

CorvusPay علامة تجارية لمالكها. هذه الإضافة غير تابعة لـ CorvusPay ولا معتمدة منها.