VibeFox PagSeguro for OpenCart — المساعدة

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعده (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

Currency: الريال البرازيلي (BRL). يجب أن تحتوي المتجر على العملة BRL (System > Localisation > Currencies)، ولا تظهر طريقة الدفع إلا عندما يُنهي العميل الطلب بالعملة BRL.

Reachable site: يجب أن يكون متجرك متاحًا عبر الإنترنت حتى تتمكن PagBank من إرسال إشعارات الدفع.

PagBank account: رمز إنتاج للمدفوعات الحقيقية ورمز بيئة اختبار (sandbox) للتجارب. الإنتاج: سجّل الدخول إلى حسابك في PagBank، وافتح Venda online > Integrações وانقر على Gerar token؛ ترسل PagBank الرمز عبر البريد الإلكتروني. بيئة الاختبار: انسخ رمز حساب الاختبار الخاص بك من بوابة المطورين في PagBank. لا تعمل رموز بيئة الاختبار ورموز الإنتاج إلا في بيئتها الخاصة.

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم الخاصة بالإصدارين من OpenCart. فُكّ ضغطه على حاسوبك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_pagseguro_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_pagseguro_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص هو نفسه للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، واختر الملف wcp_pagseguro_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت يمكنك أيضًا نسخ محتويات المجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox PagSeguro Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

4. أدخل رمز بيئة الاختبار، ولاستقبال المدفوعات الحقيقية أدخل رمز الإنتاج. لا يلزم إعداد أي شيء في PagBank: يُرسَل عنوان URL الخاص بالإشعارات مع كل دفعة.

5. فعّل Enable / Disable وانقر على Save. أجرِ مدفوعات تجريبية مع تفعيل Sandbox Mode، ثم أوقفه لتلقي المدفوعات الحقيقية.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، واختر الملف wcp_pagseguro_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة التي غُيّر اسمها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر بجوارها على Install (زر + الأخضر).

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox PagSeguro Gateway، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم الرصاص).

4. أدخل مفتاح الترخيص والرموز، واختبر المدفوعات كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها هي نفسها في الإصدارين. ويختلف فقط عنوان URL الخاص بالإشعارات (راجع Notification URL)، ويُرسَل هو أيضًا إلى PagBank مع كل دفعة.

تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة ووضع sandbox مفعّلًا.

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox PagSeguro Gateway > Edit. تظهر الأقسام في القائمة على اليسار؛ يحفظ زر Save الموجود أسفل القائمة الصفحة كاملة. وفوق الإعدادات تعرض الصفحة الوضع الحالي: SANDBOX MODE (تُنشأ المدفوعات في بيئة PagBank التجريبية دون أي خصومات حقيقية) أو LIVE (تُنشأ المدفوعات باستخدام رمز الإنتاج). وتعرض تحذيرًا عندما يكون رمز الوضع الحالي مفقودًا (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما تكون عملة المتجر الافتراضية غير BRL. ومن دون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا يمكن أن يكون حقل Title فارغًا (حتى 128 حرفًا)، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total عددًا أكبر من 0 أو يساويه، ويجب أن توجد المنطقة الجغرافية وحالات الطلب. إذا كانت قيمة ما خاطئة، فإن رسالة الخطأ تحددها ولا يُحفظ شيء.

PagSeguro / PagBank

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: PagSeguro / PagBank. مطلوب، حتى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Sort Order: ترتيب PagBank بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض PagBank فقط لعناوين الفوترة الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعَدّ المناطق الجغرافية في System > Localisation > Geo Zones. وفي OpenCart 4، عندما لا يطلب المتجر عنوان فوترة، يُستخدم عنوان الشحن.

Total: إجمالي صفحة الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب حتى يُعرض PagBank. اتركه فارغًا لعرض PagBank مهما كان الإجمالي.

حساب PagBank

يوضح هذا القسم أين تحصل على الرموز، ويحتوي على روابط إلى حسابك في PagBank وإلى صفحة PagBank الخاصة بالرموز.

Sandbox Mode: Enable sandbox/test mode (no real charges). تُرسل المدفوعات الجديدة إلى بيئة PagBank التجريبية باستخدام رمز sandbox، ويرى العملاء SANDBOX MODE — Using test environment. No real charges. في خطوة Confirm Order. تستخدم عمليات التحقق من الحالة والاسترداد الخاصة بالطلب دائمًا البيئة والرمز اللذين أُنشئت بهما مدفوعاته. الافتراضي: مفعّل.

Sandbox token: رمز بيئة PagBank التجريبية. يُستخدم أثناء تفعيل وضع sandbox.

Production token: رمز الإنتاج في PagBank (Bearer). يُستخدم عند إيقاف وضع sandbox. احتفظ به سريًا.

لا تُعرض الرموز المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها. ولإزالة رمز محفوظ، ضع علامة على Clear the saved token on save أسفل الحقل، ثم انقر على Save.

إشعارات الدفع

Notification URL: كل دفعة تُعلم PagBank بإرسال إشعارات الدفع والطلب إلى هذا العنوان، لذلك لا يوجد ما يلزم ضبطه في PagBank. في OpenCart 3 يبدو بالشكل https://your-store/index.php?route=extension/payment/wcp_pagseguro_gateway/webhook، وفي OpenCart 4 يبدو بالشكل https://your-store/index.php?route=extension/wcp_pagseguro_gateway/payment/wcp_pagseguro_gateway.webhook. ويُنشأ من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. يجب أن يكون العنوان متاحًا عبر الإنترنت.

تُتحقق الإشعارات التي تحمل ترويسة x-authenticity-token باستخدام رمز البيئة التي أُنشئ فيها الدفع، ويُرفض أي توقيع غير صالح. ولا يُوثق بمحتوى الإشعار نفسه أبدًا: تقرأ الإضافة دائمًا الدفع وطلب PagBank (الحالة والمبلغ والعملة) من واجهة برمجة تطبيقات PagBank قبل أن يتغير الطلب. وبدون الإشعارات، يحصل الطلب على حالته عندما يعود العميل إلى المتجر بعد الدفع.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تُبلغ PagBank عن الدفع عبر إشعار أو عند عودة العميل؛ ويُقرأ الدفع دائمًا من PagBank مجددًا. يسرد كل حقل أدناه حالات طلبات OpenCart الخاصة بك.

Order Status After Payment: الحالة التي تُعيَّن بعد دفعة PagBank موثَّقة. الافتراضي: قيد المعالجة.

Awaiting PagBank Payment Status: تم إصدار boleto أو PIX، أو أن الدفع قيد التحليل (WAITING / IN_ANALYSIS)؛ وتؤكد PagBank المبلغ لاحقًا. الافتراضي: قيد الانتظار.

PagBank Payment On Hold Status: يحتاج الدفع إلى مراجعتك (راجع حالات الطلب). الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment Declined Status: رُفض دفع طلب معلّق. إذا أبلغت PagBank لاحقًا بأنه مدفوع، يحصل الطلب على الحالة المخصصة لما بعد الدفع. الافتراضي: فشل.

Payment Cancelled Status: أُلغي دفع طلب معلّق في PagBank. ينقل أي دفع يصل لطلب بهذه الحالة الطلب إلى حالة المراجعة. الافتراضي: ملغى.

Refunded Status: تُعيَّن بعد استرداد الدفع بالكامل من صفحة الطلب أو من لوحة PagBank. الافتراضي: مُسترَد.

متقدم

Debug log: يكتب طلبات API والإشعارات في الملف wc_psg_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. لا تحتوي السجلات على أي رموز أو بيانات عملاء. تُسجَّل الأخطاء والتحذيرات دائمًا. الافتراضي: معطّل.

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تُحفظ الطلبات ومراجعها في PagBank (وهي مطلوبة للاسترداد) دائمًا. الافتراضي: معطّل.

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر الرموز.

Import: الصق ملف JSON الذي صدّرته سابقًا وانقر على Import لاستعادة الإعدادات. تبقى الرموز المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا PagSeguro / PagBank). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the PagBank payment page (credit card, PIX, boleto) and returned to the store. ينشئ OpenCart الطلب في هذه الخطوة، ما يزال دون حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose الموجود في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة عملية دفع في PagBank بإجمالي الطلب بالعملة BRL كعنصر واحد، هو Order # مع رقم الطلب واسم متجرك (تُحتسب القسائم والشحن والضرائب ضمن الإجمالي)، وتنقل العميل إلى صفحة الدفع الخاصة بـ PagBank. ويُمرَّر اسم العميل وبريده الإلكتروني، بالإضافة إلى CPF أو CNPJ (11 أو 14 رقمًا) من حقل مخصص للعميل أو لعنوان الدفع يحتوي اسمه على CPF أو CNPJ، ورقم هاتف برازيلي. لا يحتوي OpenCart على حقل CPF افتراضيًا؛ ويمكنك إضافته في Customers > Custom Fields. وفي OpenCart 4، عندما لا يطلب المتجر عنوان فوترة، يُستخدم عنوان الشحن وحقوله المخصصة. يمكن للعميل أن يكمل هذه البيانات أو يصححها في صفحة PagBank، ويدفع بالطرق المفعّلة في حساب PagBank الخاص بك. تنتهي صلاحية صفحة الدفع بعد 120 دقيقة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب مدفوعًا إلا بعد أن تؤكد PagBank ذلك: تقرأ الإضافة الدفع من واجهة برمجة تطبيقات PagBank عند وصول الإشعار أو عند عودة العميل، ويجب أن يطابق المبلغ المخصوم (دون فوائد التقسيط في PagBank) والعملة الطلب. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وفي حالة boleto أو PIX المُنشأ، أو دفع قيد التحليل، تعرض الصفحة أيضًا Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. وبالنسبة لطلب في حالة المراجعة تعرض We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. وإذا لم تكن PagBank قد أكدت الدفع عند عودة العميل، تعرض صفحة Payment confirmation النص نفسه مع الزرين Check again وBack to checkout.

إذا لم يكتمل الدفع، يعود العميل إلى صفحة الدفع مع الرسالة The PagBank payment was not completed. You can try again or choose another payment method. أو The PagBank payment page has expired. You can try again or choose another payment method. أو The payment was declined by PagBank. Please try again with another card or payment method. ويُحتفظ بالسلة. وفي OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع. وإذا أُلغي طلب كان ينتظر دفع boleto أو PIX، يرى العميل The PagBank payment was cancelled, so the order was cancelled. وإذا كانت السلة فارغة بالفعل (مثلًا لأن الطلب وصل إلى صفحة النجاح قبل انتهاء صلاحية boleto أو PIX)، فلا يوجد ما يُدفع في صفحة الدفع: بدلًا من ذلك تعرض صفحة Payment confirmation الرسالة؛ وبالنسبة لطلب غير مدفوع تكون الرسالة The PagBank payment of order #N was not completed (declined, canceled or expired), so the order will not be shipped. To buy these items, please place a new order. مع زر Continue.

ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order. أما OpenCart 4 فيُبقي طلبًا واحدًا للدفع ويحدّثه، لذلك بعد بطاقة مرفوضة أو دفعة غير مكتملة أو صفحة انتهت صلاحيتها يدفع العميل الطلب نفسه بعملية دفع جديدة في PagBank. وقبل إجراء دفعة جديدة، تتحقق الإضافة من عمليات الدفع السابقة في PagBank لنفس الطلب والسلة: فإذا تم الدفع في صفحة سابقة يُطبَّق ذلك بدلًا من إنشاء دفعة جديدة، وإذا كان طلب آخر في السلة مدفوعًا أو قيد الانتظار ينتقل العميل إلى صفحة النجاح. تُعاد استخدام صفحة الدفع المفتوحة للطلب إذا كان المبلغ والبيئة متطابقين ولم تنتهِ صلاحيتها خلال 10 دقائق؛ وإلا تُعطَّل فلا يمكن دفعها بعد ذلك. وإذا وصلت دفعة ثانية على كل حال، فإن ملاحظة تطلب منك استردادها.

إذا كان الطلب قد دُفع ثم أغلقته أنت (على سبيل المثال بإلغائه أو باسترداده)، فلا يُعرض على العميل العائد من PagBank صفحة النجاح، بل يعود إلى صفحة الدفع مع الرسالة Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order.، أو يراها في صفحة Payment confirmation عندما تكون السلة فارغة بالفعل.

يحتفظ OpenCart 4 بالطلب في الدفع حتى تُعرض صفحة النجاح. وإذا أُغلق ذلك الطلب في الأثناء، يعيد Confirm Order العميل إلى صفحة الدفع مع الرسالة المناسبة: رسائل الإلغاء الخاصة بـ boleto أو PIX والدفع المرفوض المذكورة أعلاه، أو Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، أو، لطلب دُفع ثم أغلقته أنت، رسالة إغلاق الطلب من المتجر. أما Confirm Order التالي فيدفع طلبًا جديدًا. وإذا كان ذلك الطلب مدفوعًا أو قيد الانتظار بالفعل وأصبحت السلة تحتوي على منتجات أو كميات أخرى، تكون الرسالة: Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it.

إذا تعذر على PagBank بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة، مثل PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. أو Could not connect to PagBank. Please try again in a moment. ويُكتب السبب التقني في السجل.

تعمل الإشعارات أيضًا أثناء وضع المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وفي OpenCart 4 تضيف الإضافة startup action يسمح بمرور الإشعارات وعودة العميل من PagBank.

لا تتضمن الإضافة نموذج بطاقة داخل الموقع، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا مدفوعات مقسّمة أو أسواق متعددة البائعين. وطرق الدفع والتقسيط هي ما هو مُعدّ في حساب PagBank الخاص بك.

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

حالات الطلب

No status (missing order): أُرسل العميل إلى PagBank ولم يدفع، أو رُفضت البطاقة، أو انتهت صلاحية صفحة الدفع؛ ويمكن للعميل الدفع مرة أخرى. تظهر هذه الطلبات في Sales > Orders فقط عند ضبط المرشح Order Status على Missing Orders.

في OpenCart 4 قد يحصل طلب غير مدفوع من عملية الدفع على الحالة Voided، التي يعيّنها OpenCart 4 عندما يعود العميل إلى خطوة Confirm Order. تعامل الإضافة هذا الطلب كطلب دون حالة، ويؤكده أي دفع لاحق.

Order Status After Payment (default Processing): تم تأكيد الدفع بالمبلغ والعملة المتوقعين. تعرض ملاحظة المبلغ وطريقة الدفع ومعرّف الخصم في PagBank.

Awaiting PagBank Payment Status (default Pending): تم إنشاء boleto أو PIX وهو بانتظار الدفع، أو أن الدفع قيد التحليل. ينتقل الطلب إلى Order Status After Payment عندما تبلغ PagBank بأنه مدفوع.

PagBank Payment On Hold Status (default Pending): أبلغت PagBank عن مبلغ أو عملة تختلف عن الطلب؛ أو وصل دفع بعد إلغاء الطلب (تحقق من المخزون، ثم أكمل الطلب أو استرد الدفع في PagBank)؛ أو أُذن بدفعة بطاقة ولم تُحصَّل (حصّلها في PagBank). وتشرح الملاحظة ذلك. ويُسجَّل المبلغ المستلم فعليًا لأغراض الاسترداد.

Payment Declined Status (default Failed): رُفض دفع كان بانتظار المعالجة أو قيد التحليل.

Payment Cancelled Status (default Canceled): أُلغي دفع كان بانتظار المعالجة، مثل boleto أو PIX انتهت صلاحيته.

Refunded Status (default Refunded): استُرد الدفع بالكامل، إما عبر الإضافة أو من لوحة PagBank.

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

علامة تبويب VibeFox PagSeguro Gateway

في Sales > Orders افتح طلبًا دُفع عبر PagBank. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox PagSeguro Gateway الـ PagBank checkout مع الوسم Sandbox لمدفوعات sandbox، ومعرّفات PagBank order وCharge، وPayment method، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد، وPagBank notes الخاصة بالطلب. وتُعرض علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

في علامة التبويب VibeFox PagSeguro Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via PagBank. أكّد السؤال Refund this amount through PagBank? This cannot be undone. يُدعم الاسترداد الكامل والجزئي. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). والحد الأقصى هو المبلغ الذي خصمته PagBank، لذلك بعد وجود اختلاف في المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. يُرسل الاسترداد في البيئة وبالرمز اللذين تمت بهما عملية الدفع. لا يُسجَّل الاسترداد إلا عندما تؤكده PagBank؛ وإلا تعرض علامة التبويب الخطأ، مثل PagBank refund failed: ... أو PagBank did not confirm the refund، ولا يُسجَّل أي شيء. وتتبع استردادات مدفوعات boleto والاسترداد الجزئي لـ PIX قواعد PagBank. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع معرّف الخصم. ويضع الاسترداد الكامل الطلب على Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا كتغيير يدوي للحالة. ولا يغيّر الاسترداد الجزئي الحالة. الاسترداد متاح بعد أن تُبلغ PagBank بأن الدفع قد تم.

لا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر PagBank.

تُرصد عمليات الاسترداد التي تتم في لوحة PagBank مع الإشعار أو التحقق التالي: يضع الاسترداد الكامل الطلب على Refunded Status، ويضيف الاسترداد الجزئي ملاحظة تتضمن المبلغ المسترد.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PagSeguro Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox PagSeguro Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموَّهًا، والحالة (مثلًا تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-pagseguro والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify على الإضافة. تتبع نصوص الكتلة لغة الإدارة (وتتضمن الإنجليزية والروسية).

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

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

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

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

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

PagBank does not appear at checkout: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن رمز الوضع الحالي مضبوط (Sandbox token في وضع sandbox وProduction token في وضع live)، وأن العميل يُنهي الطلب بالعملة BRL. تعرض صفحة الإعدادات تحذيرًا عندما يكون الرمز مفقودًا أو عندما لا تكون عملة المتجر BRL. وتحقق أيضًا من أن عنوان الفوترة ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

The payment went through, but the order stays without a status: لم تُبلغ PagBank عن الدفع بعد، ولم يعد العميل إلى المتجر. سيحصل الطلب على حالته فور وصول الإشعار. تحقق من أن متجرك متاح عبر الإنترنت على Notification URL، وفعّل Debug log لمشاهدة الإشعارات.

The notification answers Invalid signature: لا يطابق x-authenticity-token رمز البيئة التي تم فيها الدفع، أو أن هذا الرمز غير محفوظ. تحقق من وجود الرمز الصحيح في الإعدادات.

The notification answers Verification failed, retry later: تعذر الوصول إلى واجهة PagBank، أو أن رمز بيئة الدفع مفقود، أو أن السلة كانت تُعالج بطلب آخر في اللحظة نفسها. ستعيد PagBank محاولة الإشعار.

The notification answers Order not found: الإشعار يخص طلبًا لم يُدفع بهذه الإضافة في هذا المتجر. لا يتغير شيء.

The customer sees PagBank payments are temporarily unavailable. Please choose another payment method.: رمز الوضع الحالي مفقود، أو أن PagBank رفضته.

The customer sees PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: صفحة الدفع تتم بعملة أخرى.

The customer sees This order has no amount to pay.: إجمالي الطلب صفر.

Order is in the review status after payment: اقرأ الملاحظات في علامة التبويب VibeFox PagSeguro Gateway (راجع حالات الطلب)، وقارن المبالغ في PagBank، ثم أنجز الطلب أو استرد الدفع.

No refund form in the tab: تذكر علامة التبويب السبب: لم يُبلَّغ عن الدفع بعد، أو أنه مسترد بالكامل، أو أن مجموعة المستخدمين لا تملك صلاحية تعديل الإضافة، أو أن رمز بيئة الدفع غير مضبوط.

Refund fails with a message about the token: تمت عملية الدفع في بيئة sandbox أو في الإنتاج، ورمز تلك البيئة مفقود أو مرفوض. أدخل الرمز الصحيح وأعد المحاولة.

للمطورين: قبل إنشاء صفحة الدفع في PagBank، تُطلق الإضافة حدث OpenCart باسم wc_psg_checkout_data مع نص الطلب والطلب والبيئة. ويجب أن يظل البند مساويًا لإجمالي الطلب.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox PagSeguro Gateway. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. ويحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable / Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Orders، والتي تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 تُحذف أحداثها وstartup action الخاص بها، الذي يسمح بمرور الإشعارات وعودة العميل في وضع الصيانة). وإذا كان Delete Data on Uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان والوصف ووضع sandbox والرموز والتسجيل) والسجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. تُحفظ سجلات مدفوعات PagBank واستردادها دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، ولإزالة ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox PagSeguro Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لإزالة الحزمة المرفوعة.

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