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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبت ومفعّل. لا تقبل الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث.

عملة المتجر: الين الياباني (JPY). عند استخدام عملة أخرى للمتجر، تُخفى وسيلة الدفع في صفحة الدفع. في صفحة Pay for order تُعتمد عملة الطلب.

حساب GMO Payment Gateway: عقد تاجر مع GMO-PG يشمل Link Type Plus. تحتاج إلى Shop ID وShop password وConfig ID الخاص بـ Link Type Plus (設定ID) لبيئة الاختبار و/أو الإنتاج، مع تفعيل إشعار النتيجة (結果通知) في لوحة إدارة متجر GMO-PG (انظر الإعداد). لا يُستخدم Site ID أو Site password.

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

التثبيت

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

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > GMO Payment Gateway — Credit Card > Manage، أو انقر على Settings تحت اسم الإضافة في صفحة الإضافات.

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

5. أدخل Shop ID وShop password وConfig ID لبيئة الاختبار و/أو الإنتاج، واختر Environment.

6. في لوحة إدارة متجر GMO-PG، فعّل 結果通知 (إشعار النتيجة) واضبط عنوان URL للإشعار كما يظهر في الإعدادات (انظر الإعداد).

7. فعّل Enable/Disable. أجرِ دفعة اختبار في بيئة الاختبار، ثم بدّل Environment إلى الإنتاج.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > GMO Payment Gateway — Credit Card. يعرض عنوان الصفحة شارة TEST أو PRODUCTION للبيئة الحالية. تُظهر الصفحة تنبيهًا أعلى الحقول عندما لا تكون عملة المتجر JPY، أو عند غياب Shop ID أو Shop password أو Config ID للبيئة الحالية. في الحالتين، تُخفى وسيلة الدفع في صفحة الدفع. وتُعلَّم البوابة في قائمة وسائل الدفع بأنها تحتاج إلى إعداد حتى تُدخل بيانات اعتماد البيئة الحالية. تُزال المسافات المحيطة ببيانات الاعتماد عند الحفظ.

Enable/Disable: Enable GMO Payment Gateway — Credit Card يفعّل وسيلة الدفع أو يعطّلها. الافتراضي: معطّل.

Title: اسم وسيلة الدفع الظاهر في صفحة الدفع. الافتراضي: Credit card.

Description: النص الظاهر تحت وسيلة الدفع في صفحة الدفع. الافتراضي: You will be redirected to the secure GMO Payment Gateway page to pay by credit card.

حساب GMO-PG

يوجد Shop ID وShop password في لوحة إدارة متجر GMO-PG ضمن Shop management > Shop information، ويوجد Config ID ضمن Link Type Plus > Settings (設定ID). تختلف بيانات الاعتماد بين بيئتي الاختبار والإنتاج.

Environment: بيئة GMO-PG التي تستقبل المدفوعات.

بيانات اعتماد الإنتاج (p01.mul-pay.jp)

Production Shop ID: قيمة Shop ID لبيئة الإنتاج.

Production Shop password: قيمة Shop password لبيئة الإنتاج.

Production Config ID: معرّف إعداد Link Type Plus (設定ID) المسجّل في لوحة GMO-PG.

بيانات اعتماد الاختبار (pt01.mul-pay.jp)

Test Shop ID: قيمة Shop ID لبيئة الاختبار.

Test Shop password: قيمة Shop password لبيئة الاختبار.

Test Config ID: معرّف إعداد Link Type Plus (設定ID) لبيئة الاختبار.

الدفع

Capture: توقيت الخصم من البطاقة.

Order status after payment: حالة الطلب المدفوع. تُضبط فورًا، بتغيير واحد للحالة ورسالة بريد واحدة للعميل.

إشعارات الدفع (結果通知)

يُبلغ إشعار النتيجة متجرك بأن دفعة قد تمت. وهو مطلوب. في لوحة إدارة متجر GMO-PG، فعّل 結果通知 (إشعار النتيجة) واضبط عنوان URL للإشعار الظاهر في هذا القسم من الإعدادات. يكون على غرار https://your-site/wc-api/gmo_pg_webhook/. انسخ العنوان تمامًا كما يظهر في الإعدادات.

إشعارات GMO-PG غير موقّعة، لذلك لا تثق الإضافة بمحتواها مباشرةً أبدًا. يجب أن يأتي الإشعار من إحدى قيم Shop ID التي أعددتها وأن يتعلق بدفعة أنشأها هذا المتجر في البيئة التي دُفع فيها الطلب. تطلب الإضافة بعدها المعاملة من GMO-PG (SearchTrade) باستخدام Shop password، ولا تغيّر الطلب إلا بناءً على ذلك الرد. الإشعار الذي لا يطابق معاملة حقيقية لا يغيّر شيئًا. يُؤكَّد استلام إشعارات المعاملات التي لم ينشئها المتجر، مثل المعاملات المنفّذة في لوحة GMO-PG، ثم تُتجاهل. عندما يتعذر على الإضافة التحقق من إشعار، ترد بما يجعل GMO-PG يرسله مجددًا (يعيد GMO-PG المحاولة حتى 5 مرات).

بدون الإشعار، لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

إعدادات متقدمة

Debug log: Log API requests and notifications يكتبها في WooCommerce > Status > Logs، بالمصدر wcp_gmo_payment. تُسجَّل الأخطاء دائمًا. تُحجب كلمات المرور وبيانات العملاء. الافتراضي: معطّل.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. لا يؤدي التعطيل إلى حذف أي شيء. تُحفظ بيانات الطلبات (معرّفات المعاملات) دائمًا. الافتراضي: معطّل.

الدفع

يختار العميل وسيلة الدفع (افتراضيًا Credit card) ويقدّم الطلب. تنشئ الإضافة دفعة GMO-PG Link Type Plus بإجمالي الطلب، مقرّبًا إلى ينات صحيحة، وتوجّه العميل إلى صفحة دفع GMO-PG. هناك يدفع العميل بالبطاقة الائتمانية. يعالج GMO-PG ‏3-D Secure 2.0، ويُمرَّر إليه البريد الإلكتروني للفوترة الخاص بالعميل لاستخدامه في 3-D Secure. تُفتح صفحة الدفع باليابانية أو الصينية أو الإنجليزية بحسب لغة موقعك. تظهر الدفعة لدى GMO-PG مع WC- ورقم الطلب. لا تُرسل أي بيانات أخرى خاصة بالعميل.

بعد الدفع، يعود العميل إلى متجرك. يُتحقق من النتيجة الموقّعة باستخدام Shop password، ولا يُعلَّم الطلب كمدفوع إلا بعد تأكيد GMO-PG: بطلب SearchTrade من جهة الخادم عند عودة العميل، أو بإشعار النتيجة. يستخدم المساران المنطق نفسه، فلا يُعالج الطلب مرتين أبدًا. إن لم تُؤكَّد الدفعة بعد، تعرض صفحة استلام الطلب Your card payment is being confirmed by GMO Payment Gateway. You will receive an e-mail as soon as it is confirmed.

إذا رُفضت البطاقة أو فشل الدفع في صفحة GMO-PG، تصبح حالة الطلب فشل، ويُنقل العميل إلى صفحة Pay for order مع الرسالة The card payment was declined or could not be completed. Please try again or use another card. إذا غادر العميل صفحة GMO-PG دون دفع، تعرض الصفحة نفسها The payment was not completed. You can try again or choose another payment method. تلغي كل محاولة جديدة رابط الدفع السابق غير المدفوع. وإذا كان الرابط السابق قد دُفع بالفعل في هذه الأثناء، تُطبَّق تلك الدفعة ولا يُنشأ رابط جديد.

يمكن دفع الطلبات التي يتراوح إجماليها من 1 إلى 9,999,999 JPY. تُخفى وسيلة الدفع للمبالغ الأكبر. إن تعذر بدء الدفع، يرى العميل رسالة قصيرة مثل Card payment could not be started. Please try again or choose another payment method.، ويُضاف السبب إلى ملاحظات الطلب.

تعمل وسيلة الدفع في صفحة الدفع الكلاسيكية، وفي كتلتي السلة والدفع، وفي صفحة Pay for order. وتعرض في كتلة الدفع أيقونة البطاقة والوصف. في بيئة الاختبار، تعرض صفحة الدفع الكلاسيكية وكتلة الدفع كلتاهما الشارة Test mode — no real charge. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

تقبل الإضافة مدفوعات البطاقات الائتمانية بعملة JPY فقط، ودائمًا على صفحة GMO-PG. ولا تتضمن وسائل دفع GMO-PG الأخرى، ولا تعدد العملات، ولا البطاقات المحفوظة أو تسجيل أعضاء GMO-PG، ولا الاشتراكات أو الفوترة المتكررة، ولا نموذج بطاقة داخل الموقع.

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

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

Pending payment: وُجّه العميل إلى GMO-PG ولم يدفع بعد، أو لم يؤكّد GMO-PG الدفعة بعد.

Processing or Completed: أُكّدت الدفعة. تتبع الحالة إعداد Order status after payment. تعرض ملاحظة الطلب المبلغ وحالة GMO-PG والمعاملة وكيفية تأكيدها (إشعار أو عودة العميل). معرّف المعاملة هو GMO-PG TranID.

On hold (authorized): فُوّض المبلغ باستخدام Authorize only (仮売上). حصّله بإجراء الطلب Capture payment (GMO-PG) أو في لوحة GMO-PG قبل انتهاء صلاحية التفويض. بعد التحصيل، يصبح الطلب قيد التنفيذ أو مكتملًا. وإذا أُلغي التفويض لدى GMO-PG، يُلغى الطلب.

On hold after payment: أبلغ GMO-PG عن مبلغ مختلف عن إجمالي الطلب، أو وصلت الدفعة بعد إلغاء الطلب. تشرح ملاحظة الطلب ذلك. راجع الطلب ونفّذه أو أعد المبلغ.

Failed: رُفضت البطاقة أو لم يكتمل الدفع في صفحة GMO-PG.

إذا وصلت دفعة ثانية لطلب مدفوع أو مغلق بالفعل، فلا يتغير الطلب. تطلب منك ملاحظة إعادة الدفعة المكررة في لوحة GMO-PG.

التحصيل

يظهر إجراء الطلب Capture payment (GMO-PG) في الطلبات قيد الانتظار التي جرى تفويضها فقط. وهو يخصم المبلغ المفوّض. إذا لم تعد المعاملة في حالة تفويض، كأن تكون قد حُصّلت بالفعل في لوحة GMO-PG، يضيف الإجراء ملاحظة بالحالة الحالية ويتصرف وفقًا لها.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Credit card (يعرض الزر قيمة Title التي حددتها). تُدعم الاستردادات الكاملة والجزئية بوحدات ين صحيحة. تؤدي إعادة المبلغ المتبقي كاملًا إلى إلغاء معاملة GMO-PG، ويقرر GMO-PG ما إذا كانت إلغاءً (void) أم إرجاعًا. يخفض الاسترداد الجزئي مبلغ المعاملة، وتفوّض شركة البطاقة المبلغ الجديد. يُرسل الاسترداد إلى البيئة التي دُفع فيها الطلب، لذلك يجب ضبط Shop ID وShop password لتلك البيئة. إذا لم يقبل GMO-PG الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى ملاحظات الطلب.

تصل الاستردادات والإلغاءات المنفّذة في لوحة GMO-PG عبر إشعار النتيجة وتُضاف إلى ملاحظات الطلب. لا تُسجَّل تلقائيًا كاستردادات WooCommerce. أنشئ عند الحاجة استردادًا يدويًا في WooCommerce دون زر GMO-PG.

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

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

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

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

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

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

لا تظهر البطاقة الائتمانية في صفحة الدفع: تحقق من نشاط الترخيص وتفعيل Enable/Disable وأن عملة المتجر JPY، ومن إدخال Shop ID وShop password وConfig ID للبيئة الحالية. لا يمكن دفع الطلبات التي تتجاوز 9,999,999 JPY بالبطاقة. تعرض صفحة الإعدادات تحذيرًا عند وجود خطأ في العملة أو بيانات الاعتماد.

تم الدفع لكن الطلب يبقى Pending payment: إشعار النتيجة لا يعمل. في لوحة إدارة متجر GMO-PG للبيئة التي تستخدمها، تحقق من تفعيل 結果通知 ومن أن عنوان URL مطابق تمامًا للمعروض في الإعدادات. تحقق من إدخال Shop ID وShop password لتلك البيئة، لأن الإضافة تتحقق من كل إشعار باستخدامهما. فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_gmo_payment. يُؤكَّد الطلب أيضًا عند عودة العميل إلى المتجر بعد الدفع.

يعرض السجل Notification rejected: unknown ShopID: جاء الإشعار من متجر غير مدرج Shop ID الخاص به في الإعدادات. أدخل Shop ID لتلك البيئة.

يعرض السجل Notification ignored ... is not a payment of this store: لم تُنشأ المعاملة من هذا المتجر، كأن تكون قد نُفذت في لوحة GMO-PG. لا يلزم اتخاذ أي إجراء.

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

يرى العميل خطأ عند تقديم الطلب: افتح ملاحظات الطلب أو فعّل Debug log. تعرض الملاحظة رمز خطأ GMO-PG (ErrCode، ErrInfo). السبب المعتاد هو خطأ في Shop ID أو Shop password أو Config ID. تعني GMO Payment Gateway accepts payments in Japanese Yen (JPY) only. أن عملة الطلب ليست JPY.

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

فشل الاسترداد: اقرأ الرسالة. ربما دُفع الطلب في البيئة الأخرى التي لم تُضبط لها قيمتا Shop ID وكلمة المرور، أو أُلغيت المعاملة بالفعل لدى GMO-PG، أو تجاوز المبلغ ما تبقى في المعاملة.

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

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

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

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