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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث مع امتداد OpenSSL. بدون OpenSSL تعرض الإضافة خطأ في منطقة الإدارة ولا تُحمَّل طريقة الدفع.

العملة: EUR. تقبل Satispay الدفع باليورو فقط، لذلك تُخفى طريقة الدفع عندما لا تكون عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي EUR.

حساب Satispay: حساب Satispay Business. لا تنسخ أي مفتاح API: تتصل الإضافة برمز تفعيل لمرة واحدة تولّده في Satispay Business Dashboard (انظر قسم الإعداد). للاختبار تحتاج إلى حساب sandbox من Satispay، تطلبه من Satispay for developers.

موقع عام: يجب أن يكون موقعك متاحًا من الإنترنت حتى تتمكن Satispay من استدعائه عند تغيّر حالة الدفعة. لا يلزم إعداد أي شيء في Satispay لهذا الغرض.

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

التثبيت

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

2. انقر Activate.

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

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

5. اختر البيئة: فعّل Sandbox Mode للاختبارات، واتركه غير مفعّل للمدفوعات الحقيقية.

6. الصق رمز تفعيل لتلك البيئة في Activation Code واحفظ. ستعرض حالة الاتصال بعد ذلك الـ Key ID.

7. فعّل Enable/Disable واحفظ. اختبر دفعة في sandbox، ثم ألغِ تفعيل Sandbox Mode واربط البيئة الحية برمز تفعيل حي.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Satispay. يعرض قسم Satispay connection حالة البيئتين، مثل Live: Connected مع الـ Key ID أو Sandbox: Not connected، ويحدد البيئة المستخدمة. وطالما أن البيئة المستخدمة غير متصلة، تنص الصفحة على أن Satispay مخفي في الدفع حتى تتصل البيئة المستخدمة. وفي قائمة طرق الدفع في WooCommerce، يُعلَّم Satispay على أنه يحتاج إلى إعداد حتى تتصل البيئة المستخدمة، ويظهر شارة وضع الاختبار طالما أن Sandbox Mode مفعّل.

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

Checkout

ما يراه العملاء في قائمة طرق الدفع.

Title: اسم طريقة الدفع الظاهر عند الدفع. الافتراضي: Satispay.

Description: النص الظاهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Satispay connection

Sandbox Mode: Use the Satispay sandbox (staging) environment. لا تُخصم المدفوعات في sandbox. الافتراضي: معطّل. لكل من sandbox والبيئة الحية مفاتيح منفصلة: اربط كل بيئة برمز تفعيل خاص بها. وطالما أن sandbox مستخدم، يرى العملاء تحت طريقة الدفع العبارة وضع Sandbox: لا يُخصم أي مبلغ حقيقي.

Activation Code: لربط البيئة المختارة أعلاه، الصق رمز تفعيل جديدًا مكونًا من 6 أحرف واحفظ. تُولَّد رموز البيئة الحية في Satispay Business Dashboard ضمن قسم Online shop. تأتي رموز sandbox مع حساب sandbox من Satispay. يُستخدم الرمز مرة واحدة ولا يُخزَّن. اترك الحقل فارغًا للإبقاء على الاتصال الحالي.

عند الحفظ مع رمز، تُنشئ الإضافة زوج مفاتيح RSA وترسل المفتاح العام والرمز إلى Satispay، وتحفظ في قاعدة بيانات WordPress الـ Key ID ومفاتيح تلك البيئة. عند النجاح تعرض الصفحة، على سبيل المثال، Satispay Live connected. Key ID: متبوعًا بالمعرّف. إذا رفضت Satispay الرمز، تعرض الصفحة رسالة Satispay وتطلب منك التحقق من أن الرمز خاص بهذه البيئة ولم يُستخدم بعد. يُرفض الرمز الذي يحتوي على أحرف غير الأحرف والأرقام قبل إرسال أي شيء. حفظ رمز جديد لبيئة ما يستبدل اتصالها السابق.

Payment notifications

لا يلزم إعداد أي شيء في Satispay. لكل دفعة عنوان URL خاص للاستدعاء، تستدعيه Satispay عند تغيّر الدفعة، وتعيد الإضافة قراءة الدفعة من Satispay API قبل تغيير أي طلب. يعرض القسم مثالًا على هذا العنوان، وشكله: https://your-site/wc-api/satispay_payment_callback/?action=callback&order_id={order}&payment_id={uuid}. يجب أن يكون العنوان متاحًا من الإنترنت: لا وضع صيانة ولا حماية بكلمة مرور على /wc-api/.

Advanced

Debug log: Log API calls and payment events يكتب في WooCommerce > Status > Logs، المصدر wcp_satispay_gateway، بلا مفاتيح أو بيانات عملاء. الأخطاء تُسجَّل دائمًا حتى مع إيقاف هذا الخيار. الافتراضي: معطّل.

Delete data on uninstall: Remove the settings and Satispay keys when the plugin is deleted. تبقى بيانات الدفع المحفوظة في الطلبات. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Satispay) وينقر Pay with Satispay. تُنشئ الإضافة دفعة Satispay بإجمالي الطلب باليورو، مع رقم الطلب مرجعًا، وتنقل العميل إلى صفحة دفع Satispay. على الحاسوب يمسح العميل رمز QR بتطبيق Satispay. على الهاتف يؤكد العميل الدفع في التطبيق.

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

إذا غادر العميل صفحة Satispay دون الدفع، تُلغي الإضافة الدفعة لدى Satispay، فلا يمكن دفع الصفحة المتروكة بعد ذلك. يعود العميل إلى الدفع (أو صفحة Pay for order) مع الرسالة: Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. وتظهر الرسالة نفسها إذا رفض العميل الدفع في التطبيق.

يمكن للعميل دفع طلب غير مدفوع مرة أخرى، مثلًا من صفحة Pay for order. قبل إنشاء دفعة Satispay جديدة يُفحص السابق: تُلغى الدفعة المعلّقة لدى Satispay، وإذا كانت مدفوعة بالفعل يُعلَّم الطلب كمدفوع بها ولا تُنشأ دفعة ثانية.

إذا تعذر بدء الدفع، يرى العميل رسالة قصيرة ويمكنه اختيار طريقة دفع أخرى: Satispay is not available at the moment. Please choose another payment method. عندما لا يكون المتجر متصلًا أو ترفض Satispay المفاتيح، أو Unable to create the Satispay payment. Please try again or choose another payment method. للأخطاء الأخرى. يُكتب السبب في السجل.

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

تقبل الإضافة الدفعات الفردية باليورو فقط. ولا تدعم الاشتراكات أو وسائل الدفع المحفوظة أو التفويضات المسبقة أو قسائم الطعام. لا يوجد فحص مجدول للدفعات المعلّقة: إذا لم تصل إلى موقعك لا استدعاءات Satispay ولا عودة العميل، يبقى الطلب في حالة Pending payment، وتكون الدفعة ظاهرة في Satispay Dashboard.

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

Order statuses

Pending payment: أُرسل العميل إلى Satispay ولم يدفع بعد، أو لم تؤكد Satispay الدفعة بعد. تعرض ملاحظة الطلب معرّف دفعة Satispay والمبلغ والبيئة (Live أو Sandbox).

Processing or Completed: تم تأكيد الدفعة. يتبع الطلب القاعدة القياسية في WooCommerce: قيد المعالجة، أو مكتمل للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. تعرض ملاحظة الطلب دفعة Satispay والمبلغ وطريقة التحقق (الاستدعاء أو إعادة التوجيه أو الدفع). معرّف المعاملة هو معرّف دفعة Satispay.

On hold: أبلغت Satispay عن مبلغ أو عملة يختلفان عن إجمالي الطلب، أو قُبلت الدفعة بعد إلغاء الطلب. تشرح ملاحظة الطلب ذلك، وتُحفظ الدفعة كمعرّف معاملة حتى يمكن استردادها. تحقق من الدفعة في Satispay Dashboard، ثم أكمل الطلب أو استرد الدفعة.

Cancelled: أُلغيت آخر دفعة Satispay للطلب أو انتهت صلاحيتها، مثلًا لأن العميل غادر صفحة Satispay. لا تُلغي دفعة قديمة تنتهي صلاحيتها طلبًا لديه دفعة أحدث قيد التنفيذ. الطلبات التي أنشأتها في منطقة الإدارة (روابط الدفع) لا تُلغى: تبقى في حالة Pending payment مع ملاحظة، حتى يتمكن العميل من دفعها.

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

Refunds

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

لا تتحول الاستردادات التي تُجرى في Satispay Dashboard إلى استردادات في WooCommerce. وإذا لزم الأمر، أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Satispay.

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

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

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

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

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

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

لا يظهر Satispay في الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة المستخدمة متصلة (يعرض قسم Satispay connection الحالة Connected لها)، وأن العملة EUR.

تمت الدفعة، لكن الطلب يبقى Pending payment: يُحدَّث الطلب عندما تستدعي Satispay موقعك أو يعود العميل. تحقق من أن موقعك متاح من الإنترنت، وأنه لا يوجد وضع صيانة أو حماية بكلمة مرور على /wc-api/، وراجع WooCommerce > Status > Logs، المصدر wcp_satispay_gateway. الدفعة ظاهرة في Satispay Dashboard.

يرد الاستدعاء بـ Payment status unavailable, retry later أو Not configured: لم تتمكن الإضافة من قراءة الدفعة من Satispay، أو أن بيئة الطلب غير متصلة. لا يتغيّر الطلب. تحقق من حالة الاتصال والسجل.

يرد الاستدعاء بـ Busy, retry later: كان طلب آخر يحدّث الطلب في الوقت نفسه. لا يغيّر هذا الاستدعاء الطلب. سيُحدَّث بالاستدعاء التالي أو عند عودة العميل.

يرد الاستدعاء بـ Unknown payment أو Missing or invalid payment_id: لم تُنشأ الدفعة لهذا الطلب، أو أن الطلب ليس استدعاءً من Satispay. لا يتغيّر الطلب.

فشل التفعيل: رموز التفعيل تُستخدم مرة واحدة فقط. تحقق من أن الرمز يخص البيئة المختارة في Sandbox Mode (رمز حي للبيئة الحية، ورمز sandbox لـ sandbox)، ثم أنشئ رمزًا جديدًا واحفظ من جديد. إذا أفادت الصفحة بأنه تعذّر إنشاء زوج مفاتيح RSA، فاطلب من مزود الاستضافة تفعيل امتداد OpenSSL في PHP.

اختفى Satispay من الدفع بعد التحويل من sandbox إلى البيئة الحية: لكل من sandbox والبيئة الحية مفاتيح مختلفة. الصق رمز تفعيل حيًا مع إلغاء تحديد Sandbox Mode ثم احفظ.

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

فشل الاسترداد لأن البيئة لم تعد متصلة: تمت الدفعة في البيئة الحية أو sandbox، ولم تعد لتلك البيئة مفاتيح. أعد ربطها برمز تفعيل، أو استرد الدفعة من Satispay Dashboard.

فشل الاسترداد برسالة Satispay did not accept the refund: أعادت Satispay حالة غير accepted. لم يُسجّل WooCommerce الاسترداد. تحقق منه في Satispay Dashboard.

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

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

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

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