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

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

العملة: الين الياباني (JPY). تحصّل GMO-PG بالين فقط، لذلك تظهر طريقة الدفع فقط عندما تكون عملة السلة JPY. أضف JPY في International > Localization > Currencies إذا لم تكن متوفرة في متجرك بعد.

حساب 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. في الواجهة الخلفية، انتقل إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند اكتمال الرفع، اضغط Configure، أو ابحث لاحقًا عن VibeFox GMO Payment Gateway في قائمة الوحدات واضغط Configure.

3. أدخل مفتاح ترخيص VibeFox في License key ضمن كتلة الترخيص أعلى صفحة Configure، ثم اضغط Activate (راجع مفتاح الترخيص).

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

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

6. فعّل Enable/Disable واضغط Save. أجرِ دفعة تجريبية في بيئة الاختبار، ثم غيّر Environment إلى الإنتاج.

عند التثبيت، تُنشئ الوحدة حالة الطلب GMO-PG payment on hold. تقدّم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences، مع بقاء JPY مسموحًا به.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox GMO Payment Gateway > Configure. يحفظ كل زر Save الصفحة كاملة. وفوق الحقول، تحذّرك الصفحة إذا لم تكن العملة الافتراضية للمتجر JPY، وإذا كان Shop ID أو Shop password أو Config ID للبيئة الحالية مفقودًا (ويُخفى عندها خيار الدفع عند إتمام الشراء). كما تعرض البيئة النشطة: TEST — payments go to pt01.mul-pay.jp with the test credentials, no real money is charged. أو PRODUCTION — payments go to p01.mul-pay.jp. تُحذف المسافات حول بيانات الاعتماد عند الحفظ.

GMO Payment Gateway — Credit Card

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 التي تستقبل الدفعات الجديدة.

Test (sandbox): pt01.mul-pay.jp ببيانات اعتماد الاختبار (الافتراضي).

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

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

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

Production Config ID: رقم config ID الخاص بـ Link Type Plus (設定ID) المسجّل في لوحة GMO-PG.

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

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

Test Config ID: رقم config ID الخاص بـ Link Type Plus (設定ID) لبيئة الاختبار.

لا تُعرض كلمات المرور المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved passwords: ضع علامة على كلمة المرور واضغط Save لحذفها. يبقي الحقل الفارغ القيمة المحفوظة كما هي.

Payment

Capture: متى يُخصم المبلغ من البطاقة.

Capture immediately (即時売上): يُخصم المبلغ من البطاقة فورًا (الافتراضي).

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

Order status after payment: حالة الطلب المدفوع.

Processing: يصبح الطلب Payment accepted (الافتراضي).

Completed: يصبح الطلب Delivered. مناسب للمنتجات الافتراضية والقابلة للتنزيل.

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

يخبر إشعار النتيجة متجرك بأنه تمت عملية دفع. وهو إلزامي. في لوحة متجر GMO-PG فعّل 結果通知 (إشعار النتيجة) واضبط العنوان المعروض في Notification URL في هذا القسم. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_gmo_payment/notify، وقد يتضمن رمز لغة مثل /ja/. انسخ العنوان تمامًا كما تعرضه الإعدادات. يجب أن يكون متاحًا من الإنترنت؛ ووضع الصيانة لا يحجبه.

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

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

Advanced

Debug log: يكتب طلبات واجهة API والإشعارات في logs/gmo_pg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائمًا حتى عندما يكون المفتاح معطّلًا. تُحجب كلمات المرور وبيانات العملاء. الافتراضي: معطّل.

Log: يعرض حجم السجل وأحدث إدخالاته. اضغط Clear log لتفريغه.

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والسجل. تبقى بيانات الطلبات (GMO OrderID، ومعرّفات المعاملات) محفوظة دائمًا. الافتراضي: معطّل.

إتمام الشراء

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

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

إذا رُفضت البطاقة أو فشل الدفع في صفحة GMO-PG، يعود العميل إلى إتمام الشراء ويرى الرسالة 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.، ويُكتب السبب في السجل.

يعمل الإشعار والعودة حتى عندما يكون المتجر في وضع الصيانة، ولا يحجبهما قيد الدول في متجرك.

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

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى GMO-PG ولم يدفع، أو لم يؤكد GMO-PG الدفع بعد. لا توجد إلا السلة.

Payment accepted أو Delivered: تم تأكيد الدفع. تتبع الحالة Order status after payment. يُسجَّل الدفع مع TranID الخاص بـ GMO-PG بوصفه معرّف المعاملة، وتعرض ملاحظة المبلغ وحالة GMO-PG والمعاملة وطريقة التأكيد (إشعار أو عودة).

GMO-PG payment on hold (مفوَّض): مع Authorize only (仮売上) فُوِّض المبلغ. حصّله باستخدام Capture payment (GMO-PG) أو في لوحة GMO-PG قبل انتهاء صلاحية التفويض. بعد التحصيل يصبح الطلب Payment accepted أو Delivered. وإذا أُلغي التفويض لدى GMO-PG، يصبح الطلب Canceled.

GMO-PG payment on hold بعد الدفع: أبلغ GMO-PG عن مبلغ يختلف عن إجمالي السلة، أو لم تكن السلة بالين. توضح الملاحظة السبب، ويُسجَّل الدفع بالمبلغ الذي حصّله GMO-PG فعلًا. راجع الطلب وأنجزه أو استرد الدفعة.

Refunded: استُرد الدفع بالكامل عبر الوحدة. يؤدي الاسترداد الكامل لتفويض لم يُحصَّل أبدًا إلى تعيين الحالة Canceled.

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

كتلة GMO Payment Gateway

تعرض صفحة الطلب كتلة GMO Payment Gateway تتضمن GMO OrderID وTransaction ID والحالة (مع حالة GMO-PG) وPaid / refunded وشارة TEST للدفعات التجريبية وسجل الاستردادات وGMO-PG notes الخاصة بالطلب. يتطلب التحصيل والاسترداد صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات الوحدات.

التحصيل

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

الاستردادات

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

لا تُنشئ الوحدة إشعارات ائتمان. ولا تعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب الأموال عبر GMO-PG.

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox GMO Payment Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox GMO Payment Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل التاريخ الذي تبقى فيه الرخصة نشطة ونطاقك)، وأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: presta-payment-gmo ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يستطيع تغيير المفتاح سوى الموظفين الذين لديهم صلاحية Configure للوحدة. وتتبع نصوص الكتلة لغة الواجهة الخلفية (تشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on متبوعةً بتاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير فتحة نطاق في حسابك، اضغط Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد فقط: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. ولا يؤدي حذف المفتاح من المتجر إلى تحرير فتحة النطاق. حرّر الفتحة من حسابك في vibefox.net.

بدون مفتاح نشط، لا يُعرض الدفع ببطاقة GMO-PG للعملاء في إتمام الشراء. وإذا بدأت دفعة مع ذلك، يرى العميل This payment method is not available. Please choose another one. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى الواجهة الخلفية، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها في إتمام الشراء. ويظهر تذكير في Modules > Module Manager على علامة التبويب Alerts. ولا تتأثر الطلبات الحالية: فالدفعات التي بدأت بالفعل ما زالت تُؤكَّد، وتعمل التحصيلات والاستردادات.

عند انتهاء صلاحية الترخيص، تواصل الوحدة العمل، لكن التحديثات والدعم يتطلبان التجديد. وتُعاد مراجعة الحالة تلقائيًا أثناء عملك في الواجهة الخلفية: مرة واحدة يوميًا خلال أول 14 يومًا بعد إدخال المفتاح، ثم مرة أسبوعيًا. ولا حاجة إلى cron job. ويؤدي إلغاء تثبيت الوحدة أو إعادة ضبطها دائمًا إلى حذف مفتاح الترخيص وحالته.

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

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

تمت عملية الدفع لكن لم يُنشأ أي طلب: إشعار النتيجة لا يعمل. في لوحة متجر GMO-PG للبيئة التي تستخدمها، تحقق من أن 結果通知 مفعّل وأن العنوان مطابق تمامًا للعنوان المعروض في Notification URL. وتحقق من أن Shop ID وShop password لتلك البيئة مملوءان، لأن الوحدة تتحقق من كل إشعار بهما. فعّل Debug log وانظر إلى الحقل Log في صفحة الوحدة. كما يُنشأ الطلب عندما يعود العميل إلى المتجر بعد الدفع.

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

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

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

يعرض السجل Cannot create the order: the module is disabled: عُطِّلت الوحدة أثناء تأكيد دفعة. فعّلها؛ وسيعيد GMO-PG إرسال الإشعار.

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

الطلب في حالة GMO-PG payment on hold: اقرأ الملاحظات في كتلة GMO Payment Gateway. الطلب مفوَّض فقط وينتظر التحصيل، أو أن المبلغ المدفوع يختلف عن السلة.

يفشل الاسترداد أو التحصيل: اقرأ الرسالة في الكتلة. فربما دُفع الطلب في البيئة الأخرى التي لم يُضبط Shop ID وكلمة المرور الخاصان بها، أو ربما أُلغيت المعاملة لدى GMO-PG، أو ربما يتجاوز المبلغ ما تبقى في المعاملة. أما The order is being updated by GMO-PG right now. Try again in a moment. فتعني أن إشعارًا كان يُعالَج في الوقت نفسه.

تعرض الكتلة You do not have permission to refund orders.: ملفك الوظيفي لا يملك صلاحية تعديل الطلبات. اطلب من مدير النظام منحها لك.

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox GMO Payment Gateway، ثم اختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Delete data on uninstall مفعّلًا، تُحذف إعدادات البوابة والسجل. وإذا كان معطّلًا، تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ معاملات GMO-PG واستردادها وحالة الطلب GMO-PG payment on hold دائمًا، لذلك يمكن تحصيل الطلبات المدفوعة سابقًا واستردادها بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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