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

المتطلبات

WordPress: 6.2 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة دونه؛ وإذا أُوقف WooCommerce لاحقًا فلن تُحمَّل البوابة، وسيظهر إشعار للمسؤول.

PHP: 8.0 أو أحدث.

HTTPS: حقول البطاقة موجودة في صفحة الدفع، لذا يجب تقديم صفحة الدفع عبر HTTPS وخلوّها من البرامج النصية غير الموثوقة. ومع ذلك لا تصل بيانات البطاقة إلى خادمك أبدًا. ولا يرسل Omise الـ webhook إلا إلى عناوين HTTPS.

عملة المتجر: واحدة من THB وJPY وSGD وMYR وUSD وEUR وGBP وAUD وCAD وCHF وCNY وDKK وHKD. وبالنسبة للعملات الأخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب Omise: تحتاج إلى المفتاح العام والمفتاح السري لحساب Omise الخاص بك، لوضعي الاختبار والإنتاج معًا، وتجدهما في Settings > Keys ضمن لوحة تحكم Omise، إلى جانب نقطة نهاية webhook في Settings > Webhooks (راجع الإعدادات).

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل مفاتيح Omise الخاصة بالاختبار والإنتاج، وأضف في لوحة تحكم Omise عنوان الـ webhook المعروض في صفحة الإعدادات (راجع الإعدادات).

6. فعّل Enable/Disable. جرّب دفعة في وضع الاختبار ببطاقة اختبار من Omise، مثل 4242 4242 4242 4242، ثم ألغِ تحديد Test mode.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Omise. وفوق الحقول تعرض الصفحة Test mode is on — orders are charged with the test keys, no real money is moved. طالما وضع الاختبار مفعّل، وتحذّرك إذا كان المفتاح العام أو السري للوضع الحالي مفقودًا، أو إذا كانت عملة المتجر غير مدعومة من Omise. وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع. وفي قائمة طرق الدفع يُعرض Omise على أنه يحتاج إلى إعداد حتى يُدخل المفتاحان الخاصان بالوضع الحالي.

عام

Enable/Disable: Enable card payments via Omise يفعّل طريقة الدفع أو يعطّلها. الافتراضي: معطّل.

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

Description: النص الذي يظهر فوق نموذج البطاقة في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via Omise.

مفاتيح API

تجد مفاتيحك في لوحة تحكم Omise ضمن Settings > Keys. تبدأ مفاتيح الاختبار بـ pkey_test_ وskey_test_، وتبدأ مفاتيح الإنتاج بـ pkey_ وskey_. وعند الحفظ يُرفض أي مفتاح ببادئة خاطئة (مثل مفتاح اختبار في حقل الإنتاج) مع ظهور خطأ، ويبقى القيم السابقة كما هي.

Test mode: Use the test keys (no real charges). يبدّل المفتاحين معًا. تستخدم الاستردادات وعمليات التحصيل وفحوص حالة أي طلب دائمًا مفاتيح الوضع الذي دُفع فيه الطلب. الافتراضي: مفعّل.

Test public key: المفتاح العام لوضع الاختبار، pkey_test_...

Test secret key: المفتاح السري لوضع الاختبار، skey_test_...

Live public key: المفتاح العام لوضع الإنتاج، pkey_...

Live secret key: المفتاح السري لوضع الإنتاج، skey_...

الدفع والـ webhook

يعرض هذا القسم عنوان الـ webhook الخاص بمتجرك. ويبدو هكذا: https://your-site/wp-json/omise-payment/v1/webhook. انسخه تمامًا كما تعرضه الإعدادات، وأضفه في لوحة تحكم Omise ضمن Settings > Webhooks (HTTPS فقط). تتعامل الإضافة مع هذه الأحداث:

لا يُوثَق محتوى الـ webhook أبدًا: يجب أن تكون عملية الخصم هي المحفوظة في الطلب، ويُعاد قراءة حالتها من واجهة Omise البرمجية باستخدام مفاتيح وضع الطلب. ومن دون الـ webhook يبقى الطلب الذي أغلق فيه العميل المتصفح أثناء 3-D Secure في حالة انتظار حتى تشغّل Omise: Sync payment status، ولا تُلتقط تلقائيًا عمليات التحصيل التي تتم في لوحة تحكم Omise.

Payment action: ما الذي يحدث لمبلغ البطاقة.

Per-charge webhook: Send the webhook URL with every charge. مفيد عندما تشترك عدة متاجر في حساب Omise واحد. ويعمل فقط إذا كان الموقع يستخدم HTTPS؛ وإلا يُستخدم الـ webhook المضبوط في لوحة التحكم. الافتراضي: معطّل.

متقدم

Debug log: Log API requests and payment events يكتب خطوات الدفع في WooCommerce > Status > Logs، بالمصدر wcp_omise_payment. لا تُسجَّل المفاتيح ولا الرموز ولا بيانات البطاقة أبدًا. الافتراضي: معطّل.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit / Debit Card) ويملأ نموذج البطاقة: Name on card وCard number وExpiry month (MM) وExpiry year (YYYY) وSecurity code (CVV). وفي وضع الاختبار يعرض النموذج TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made.. وعند تقديم الطلب يحوّل Omise.js البطاقة في المتصفح إلى رمز دفع لمرة واحدة. ولا تُرسَل حقول البطاقة إلى خادمك أبدًا.

ينشئ متجرك عملية الخصم باستخدام المفتاح السري بقيمة إجمالي الطلب وبعملة الطلب. ويكون وصف الخصم اسم المتجر ورقم الطلب، ويُحفظ معرّف الطلب ضمن البيانات الوصفية لعملية الخصم. وإذا طلب البنك 3-D Secure يُوجَّه العميل إلى البنك ثم يعود إلى متجرك. وتُعاد قراءة النتيجة دائمًا من واجهة Omise البرمجية.

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

إذا رُفضت البطاقة يبقى العميل في صفحة الدفع مع Payment failed: وسبب، مثل عدم كفاية الرصيد أو رمز أمان غير صالح أو رفض من الجهة المصدِرة للبطاقة، ويمكنه المحاولة مرة أخرى. وبعد فشل 3-D Secure يُنقل العميل إلى صفحة Pay for order. وإذا تعذّر تأكيد الدفع فور انتهاء 3-D Secure يرى العميل We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

لا تؤدي المحاولة المعادة إلى خصم مزدوج أبدًا: إذا كانت عملية الخصم السابقة للطلب مدفوعة أو مفوَّضة بالفعل، يُكمَل الطلب دون خصم جديد. وتنتهي محاولات 3-D Secure غير المكتملة قبل إنشاء أي خصم جديد.

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

تقبل الإضافة مدفوعات البطاقات فقط. ولا تتضمن طرق الدفع الأخرى في Omise (PromptPay وTrueMoney والخدمات المصرفية عبر الهاتف والتقسيط وKonbini وPayNow)، ولا البطاقات المحفوظة أو عملاء Omise، ولا الاشتراكات، ولا التحصيل الجزئي.

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

حالات الطلب

في انتظار الدفع: العميل في صفحة 3-D Secure أو لم يُكمل الدفع بعد.

قيد التجهيز: تم تأكيد الدفع. الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط تصبح مكتملة، كالمعتاد في WooCommerce. وتعرض ملاحظة الطلب المبلغ ومعرّف عملية الخصم وطريقة التأكيد (الدفع، أو العودة من 3-D Secure، أو الـ webhook، أو التحصيل اليدوي، أو المزامنة اليدوية). معرّف المعاملة هو معرّف عملية الخصم في Omise (chrg_...).

في الانتظار، بانتظار التحصيل: البطاقة فوّضت باستخدام Authorize only. استخدم Omise: Capture payment أو Omise: Void authorization.

في الانتظار، الدفع معلّق: لم تؤكد Omise الدفع بعد، على سبيل المثال لأن العميل أغلق المتصفح أثناء 3-D Secure. ويحدّث الـ webhook أو Omise: Sync payment status الطلب.

في الانتظار، عدم تطابق: مبلغ عملية الخصم أو عملتها يختلف عن الطلب. وتعرض الملاحظة القيمتين. تحقّق من الطلب وأكمله أو استرد الدفعة.

فشل: رُفض الدفع. ولا يُخفَّض الطلب المدفوع أبدًا بسبب حدث فشل لاحق.

ملغى: انتهت صلاحية عملية الخصم أو أُلغي التفويض.

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

إجراءات الطلب

Omise: Capture payment: يحصّل كامل المبلغ المفوَّض. ويظهر فقط للطلبات المفوَّضة.

Omise: Void authorization: يلغي التفويض؛ لا يُحصَّل أي مبلغ ويُلغى الطلب. ويظهر فقط للطلبات المفوَّضة.

Omise: Sync payment status: يقرأ عملية الخصم من Omise ويحدّث الطلب. وتعرض الملاحظة أيضًا إجمالي المبلغ المسترد في Omise.

الاستردادات

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

لا تُستورد الاستردادات التي تتم في لوحة تحكم Omise كاستردادات في WooCommerce. ويعرض Omise: Sync payment status إجمالي المبلغ المسترد؛ وأنشئ استردادات يدوية مطابقة في WooCommerce إذا لزم الأمر.

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

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

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

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

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

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

لا يظهر Omise في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاحين الخاصين بالوضع الحالي مُدخَلان (مفاتيح الاختبار في وضع الاختبار، ومفاتيح الإنتاج في غير ذلك)، وأن العملة مدعومة. وفي صفحة Pay for order تُحتسب عملة الطلب. وتعرض صفحة الإعدادات تحذيرًا عند خطأ المفاتيح أو العملة.

تم الدفع لكن الطلب يبقى في حالة انتظار الدفع أو في الانتظار: الـ webhook لا يعمل. في لوحة تحكم Omise تحقّق من أن عنوان الـ webhook مطابق تمامًا للعنوان الظاهر في الإعدادات ويستخدم HTTPS. ثم شغّل Omise: Sync payment status على الطلب. فعّل Debug log لرؤية ردود الـ webhook.

يرد الـ webhook بـ Earlier charge of the order, order not changed: الحدث يخص محاولة سابقة للطلب استُبدلت بمحاولة معادة. لا يتغير شيء في الطلب. وإذا كانت عملية الخصم السابقة لا تزال مدفوعة أو مفوَّضة في Omise، فستنبّه ملاحظة الطلب إلى ذلك مرة واحدة: تحقّق في لوحة تحكم Omise من وجود دفع مزدوج، واسترد المبلغ أو ألغِه هناك.

يرد الـ webhook بـ Charge ID does not match order: عملية الخصم في الحدث تخص طلبًا آخر. لا يتغير شيء.

يرد الـ webhook بـ Order is being processed, retry later أو Failed to verify charge: كان الطلب مقفلًا بواسطة طلب آخر، أو تعذّر الوصول إلى واجهة Omise البرمجية. وستعيد Omise إرسال الـ webhook.

خطأ عند الحفظ: key must start with ... أو must be a live key: لُصق مفتاح في الحقل الخطأ. تبدأ مفاتيح الاختبار بـ pkey_test_ / skey_test_، وتبدأ مفاتيح الإنتاج بـ pkey_ / skey_.

يرى العميل Card payments are temporarily unavailable: المفاتيح غير صحيحة، أو رمز البطاقة يخص وضعًا آخر (رمز اختبار في وضع الإنتاج أو العكس). تحقّق من المفاتيح ومن Test mode.

يرى العميل We could not reach the payment provider: لم تصل من Omise أي استجابة صالحة أثناء إنشاء عملية الخصم. ربما أُنشئت عملية الخصم رغم ذلك؛ وتطلب ملاحظة الطلب منك التحقق من لوحة تحكم Omise قبل تحصيل مبلغ الطلب مرة أخرى.

يرى العميل This order is already being paid: قُدِّمت صفحة الدفع مرتين في اللحظة نفسها. على العميل الانتظار والتحقق من بريده الإلكتروني قبل المحاولة مرة أخرى.

الطلب في حالة انتظار بعد الدفع: اقرأ ملاحظة الطلب. إما أن الطلب بانتظار التحصيل، أو أن Omise لم تؤكد الدفع بعد، أو أن المبلغ أو العملة يختلف عن الطلب.

يفشل الاسترداد برسالة تتعلق بالوضع: دُفع المبلغ في وضع الاختبار أو الإنتاج، والمفتاح السري لذلك الوضع غير مُدخل. أدخله وأعد المحاولة.

يفشل الاسترداد الجزئي لطلب مفوَّض: الدفع مفوَّض فقط. حصّله أولًا، أو استرد المبلغ كاملًا لإلغائه.

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

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

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

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