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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: HUF أو EUR أو USD. لا تقبل SimplePay عملات أخرى، ولا تُعرض طريقة الدفع لها.

حسابات تاجر SimplePay: تمنح SimplePay حساب تاجر منفصلًا لكل عملة، وحسابات منفصلة لبيئتي الإنتاج والاختبار (sandbox). لكل حساب تحتاج إلى MERCHANT وSECRET KEY من لوحة تاجر SimplePay (admin.simplepay.hu للإنتاج، وsandbox.simplepay.hu للاختبار)، من الحساب > البيانات التقنية. إذا كنت تبيع بعملة HUF فقط فحساب HUF يكفي. لا تحتاج إلى أي مفاتيح أخرى.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل MERCHANT وSECRET KEY لحسابات SimplePay لكل عملة تبيع بها: حسابات الاختبار (sandbox) للتجارب، والحسابات الفعلية (الإنتاج) للمدفوعات الحقيقية (انظر الإعدادات).

6. انسخ IPN URL المعروض في صفحة الإعدادات إلى كل حساب تاجر (إنتاج واختبار) في لوحة تاجر SimplePay.

7. فعّل Enable/Disable، واختبر دفعة بتفعيل Sandbox mode، ثم ألغِ تحديد Sandbox mode لقبول المدفوعات الحقيقية.

عند التحديث من الإصدار 1.0، تُنقل قيم Merchant ID وSecret key الفردية في الإصدار 1.0 إلى حساب عملة المتجر في الوضع الذي كان نشطًا (الاختبار أو الإنتاج). تحقّق من الحسابات بعد التحديث.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > SimplePay (OTP). وتعرض الصفحة فوق الحقول تحذيرًا إذا كانت عملة المتجر غير مدعومة من SimplePay، أو إذا لم يكن لعملة المتجر حساب تاجر في الوضع الحالي. وفي الحالتين لا تُعرض طريقة الدفع للطلبات بتلك العملة. وأثناء تفعيل وضع الاختبار تعرض الصفحة Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged. وفي قائمة طرق الدفع يُعلَّم SimplePay بأنه يحتاج إلى إعداد حتى يكون في الوضع الحالي حساب تاجر واحد على الأقل.

عام

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

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

Description: النص المعروض أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via SimplePay. ويجب على التجار المجريين عرض إقرار نقل البيانات الخاص بـ SimplePay (Adattovábbítási nyilatkozat) في صفحة الدفع. ويمكنك إدراجه هنا مع رابطه.

Sandbox mode: Use the SimplePay sandbox يرسل المدفوعات إلى بيئة الاختبار (sandbox) في SimplePay ويستخدم حسابات الاختبار. ويبدّل عنوان واجهة البرمجة وحسابات التاجر معًا. لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. ألغِ التحديد لقبول مدفوعات حقيقية بالحسابات الفعلية.

حسابات التاجر الفعلية (الإنتاج)

الحسابات المستخدمة عندما يكون Sandbox mode معطّلًا. أدخل حسابات العملات التي يبيع بها متجرك. وقيم MERCHANT وSECRET KEY موجودة في لوحة تاجر SimplePay (admin.simplepay.hu)، في الحساب > البيانات التقنية. ولا يُستخدم الحساب إلا إذا تم ملء الحقلين.

HUF account — Merchant ID: قيمة MERCHANT لحساب HUF الفعلي.

HUF account — Secret key: قيمة SECRET KEY لحساب HUF الفعلي.

EUR account — Merchant ID وEUR account — Secret key: الأمر نفسه لحساب EUR الفعلي.

USD account — Merchant ID وUSD account — Secret key: الأمر نفسه لحساب USD الفعلي.

حسابات التاجر في بيئة الاختبار (sandbox)

الحسابات المستخدمة عندما يكون Sandbox mode مفعّلًا. الحقول هي نفسها في الحسابات الفعلية: HUF account — Merchant ID، وHUF account — Secret key، والأزواج نفسها لعملتي EUR وUSD. خذ القيم من لوحة تاجر بيئة الاختبار في SimplePay (sandbox.simplepay.hu)، من الحساب > البيانات التقنية.

IPN URL

إشعار IPN هو الرسالة التي ترسلها SimplePay إلى متجرك عند تغيّر حالة الدفع، وهو الطريقة المعتادة لتحويل الطلب إلى مدفوع. تعرض صفحة الإعدادات عنوان IPN URL لمتجرك، ويكون بالشكل التالي: https://your-site/wc-api/simplepay_payment_callback/. اضبط هذا العنوان لكل حساب تاجر، الفعلي والتجريبي (sandbox)، في لوحة تاجر SimplePay. وإذا كان موقعك يستخدم بادئة لغة في الروابط أو يعيد توجيه عناوين أخرى، فانسخ العنوان تمامًا كما تعرضه الإعدادات، لأن إشعار IPN المُعاد توجيهه يضيع.

يجب توقيع IPN بالمفتاح SECRET KEY لحساب التاجر الذي يذكره. تُرفض إشعارات IPN التي لا توقيع صالح لها. ويؤكد الإضافة كل IPN صالح لدى SimplePay بالصيغة الموقعة التي تطلبها SimplePay. وتغيّر حالات IPN التالية الطلب:

تُعيَّن حالتا «فشل» و«ملغي» فقط لآخر محاولة دفع لطلب ما زال «بانتظار الدفع». وتُسجَّل الحالات الأخرى دون أن تغيّر الطلب. ومن دون IPN لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد دفع ناجح.

الطلبات

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

متقدم

Logging: Enable logging يكتب استدعاءات API وإشعارات IPN والعودات في WooCommerce > Status > Logs، بالمصدر wcp_simplepay_gateway. لا تُسجَّل المفاتيح وبيانات العملاء. وتُسجَّل الأخطاء دائمًا حتى عند تعطيل هذا الخيار. الافتراضي: معطّل.

Delete Data on Uninstall: Remove all plugin data when uninstalling. عند التفعيل، يؤدي حذف الإضافة إلى إزالة إعدادات البوابة وسجلات الإضافة. أما بيانات الطلبات فتُحفظ دائمًا. الافتراضي: معطّل.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا SimplePay (Card Payment)) ويُتمّ الطلب. تبدأ الإضافة عملية دفع بالبطاقة عبر SimplePay بمبلغ إجمالي الطلب بعملة الطلب، باستخدام حساب التاجر لتلك العملة في الوضع الحالي، ثم تُرسل العميل إلى صفحة الدفع في SimplePay. وتعرض الصفحة ما يسمح به حساب التاجر الخاص بك لمدفوعات البطاقات. ويُمرَّر بريد العميل الإلكتروني، وعنوان الفوترة إذا كان مكتملًا، إلى SimplePay. وتستخدم صفحة الدفع لغة موقعك إذا كانت SimplePay تدعمها، وإلا فالإنجليزية. ويمكن إكمال الدفع المبدوء خلال 30 دقيقة.

بعد الدفع الناجح يعود العميل إلى صفحة استلام الطلب في متجرك. ولا تكفي العودة وحدها لاعتماد الدفع: تطلب الإضافة من SimplePay حالة المعاملة بطلب موقَّع، فيُؤكَّد الطلب حتى لو تأخر إشعار IPN. وتعرض صفحة استلام الطلب Successful transaction. SimplePay transaction ID: والمعرّف. وإذا لم يُؤكَّد الدفع بعد، تعرض Your payment is being confirmed by SimplePay. SimplePay transaction ID: والمعرّف.

إذا فشل الدفع أو أُلغي أو انتهت مهلته، يُعاد العميل إلى صفحة الدفع، أو إلى صفحة Pay for order إذا كانت السلة فارغة. هناك يرى رسالة SimplePay مع معرّف المعاملة، مثل Cancelled payment. You cancelled the payment أو Timeout. The time allowed to complete the payment has expired. وعند فشل الدفع يُطلب من العميل التحقق من البيانات التي أدخلها والتواصل مع البنك المُصدِر للبطاقة. ويمكن للعميل المحاولة مرة أخرى. وتحصل كل محاولة جديدة على مرجع SimplePay خاص بها، مثل 123 و123-2 و123-3.

إذا تعذّر على SimplePay بدء الدفع، يرى العميل The SimplePay payment could not be started. Please try again or choose another payment method. وإذا لم يكن لعملة الطلب حساب تاجر، تكون الرسالة SimplePay is not available for the currency of this order. Please choose another payment method. ويُضاف السبب التقني إلى ملاحظات الطلب والسجل. ويرى مديرو المتجر المسجّلون الدخول السبب في الرسالة أيضًا.

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

تقبل الإضافة مدفوعات بطاقات لمرة واحدة فقط، تُحصَّل في صفحة SimplePay. ولا تتضمن البطاقات المحفوظة أو الدفع بنقرة واحدة، ولا الاشتراكات أو المدفوعات المتكررة، ولا التفويض والتحصيل المنفصلان.

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

حالات الطلب

Pending payment: أُرسل العميل إلى SimplePay ولم يدفع بعد، أو لم تؤكد SimplePay الدفع بعد. تعرض ملاحظة الطلب المعاملة المبدوءة والمبلغ والوضع (الاختبار أو الإنتاج).

Processing or Completed: تم تأكيد الدفع. وتتبع الحالة الإعداد Order Status After Payment. تعرض ملاحظة الطلب معرّف المعاملة وما إذا كان إشعار IPN أو طلب الحالة هو الذي أكّد الدفع. ويُحفظ معرّف معاملة SimplePay كمعرّف معاملة للطلب. وأي دفع ناجح متأخر يُكمل أيضًا طلبًا كان «فشل» أو «ملغي».

On hold: تغيّر إجمالي الطلب أو عملته بعد بدء الدفع، لذلك لا يطابق المبلغ المدفوع الطلب. وتعرض ملاحظة الطلب المبلغين معًا. افحص الطلب ثم نفّذه أو استرد الدفع.

Failed: أبلغت SimplePay بأن آخر محاولة دفع غير مصرّح بها أو أنها احتيال.

Cancelled: أبلغت SimplePay بأن آخر محاولة دفع انتهت مهلتها أو أُلغيت.

لا يُعاد فتح الطلب المسترد أو المكتمل بإشعار IPN متأخر. وإذا نجح دفع ثانٍ لطلب مدفوع بالفعل، فلا يُعدَّل الطلب مرة أخرى. وتطلب منك ملاحظة مراجعته في لوحة SimplePay واستردادها إذا كان مكررًا.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via SimplePay (OTP). ويُدعم الاسترداد الكامل والجزئي. ويجب أن تكون استردادات HUF بفورنت صحيحة. يُرسل الاسترداد بحساب التاجر والوضع (الاختبار أو الإنتاج) اللذين تمت بهما عملية الدفع، لذلك يجب أن يبقى ذلك الحساب في الإعدادات. وإذا لم تقبل SimplePay الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف معاملة الاسترداد في SimplePay والسبب إذا أدخلته.

لا تُزامَن الاستردادات التي تُجرى في لوحة تاجر SimplePay مع WooCommerce. سجّلها يدويًا في WooCommerce دون استخدام Refund via SimplePay (OTP).

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

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

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

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

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

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

لا تظهر SimplePay في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن عملة الطلب HUF أو EUR أو USD، وأن لتلك العملة Merchant ID وSecret key معًا في الوضع الحالي: حسابات الاختبار ما دام Sandbox mode مفعّلًا، والحسابات الفعلية ما دام معطّلًا. وتعرض صفحة الإعدادات تحذيرًا عندما لا يكون لعملة المتجر حساب.

تم الدفع لكن الطلب ما زال «بانتظار الدفع»: لم يصل إشعار IPN إلى المتجر. في لوحة تاجر SimplePay تحقّق من عنوان IPN URL لحساب التاجر الذي تستخدمه (الفعلي أو التجريبي، وعملة الطلب). ويجب أن يكون مطابقًا تمامًا للعنوان المعروض في الإعدادات، وأن يكون خادمك متاحًا من الإنترنت. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

يرد IPN بـ Invalid signature: يشير IPN إلى حساب تاجر غير موجود في الإعدادات، أو أن Secret key خاطئ. أدخل MERCHANT وSECRET KEY تمامًا كما تعرضهما لوحة تاجر SimplePay. وتعيد SimplePay إرسال إشعارات IPN غير المؤكدة.

يرد IPN بـ Order not found أو Unknown transaction: الإشعار يخص طلبًا أو معاملة لم يبدأها هذا المتجر. ولا يتغيّر الطلب.

يرد IPN بـ Busy, retry: كان الطلب يُؤكَّد في الوقت نفسه بطلب آخر. وستعيد SimplePay محاولة إشعار IPN.

يرى العميل خطأ عند إتمام الطلب: افتح ملاحظات الطلب، أو راجع WooCommerce > Status > Logs، بالمصدر wcp_simplepay_gateway. فمفتاح secret key خاطئ يُظهر Invalid response signature from SimplePay. Check the secret key of the merchant account. وتُعرض أخطاء SimplePay بالشكل SimplePay error code(s): متبوعًا بالرموز.

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

الطلب في وضع «On hold» بعد الدفع: اقرأ ملاحظة الطلب. تغيّر إجمالي الطلب أو عملته بعد بدء الدفع. نفّذ الطلب أو استرد الدفع.

فشل الاسترداد: اقرأ الرسالة. SimplePay refunds in HUF must be whole amounts. تعني أن مبلغ HUF كان يحتوي على كسور عشرية. وإذا قالت الرسالة إن حساب التاجر لهذا الدفع غير مُهيّأ، فأعد إدخال الحساب (العملة والوضع) الذي تم به الدفع. وإذا استردت SimplePay مبلغًا مختلفًا، فستطلب الرسالة منك مراجعة الاسترداد في لوحة SimplePay.

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

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

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

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