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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

العملة: الريال البرازيلي (BRL). تُعرض طريقة الدفع فقط للسلات بعملة BRL.

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

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

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

التثبيت

1. في لوحة الإدارة انتقل إلى Modules > Module Manager وانقر Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، انقر Configure، أو ابحث لاحقًا عن VibeFox PagSeguro Gateway في قائمة الوحدات وانقر Configure.

3. أدخل مفتاح ترخيص VibeFox في License key داخل كتلة الترخيص أعلى صفحة Configure، وانقر Activate (انظر مفتاح الترخيص).

4. أدخل رمز sandbox، ولاستقبال المدفوعات الفعلية أدخل رمز الإنتاج.

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

عند التثبيت تُنشئ الوحدة حالتين للطلب، هما Awaiting PagBank payment وPagBank payment on hold. تعرض PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ ويجب أن تبقى عملة BRL مسموحة للوحدة.

الإعداد

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول تعرض الصفحة الوضع الحالي: SANDBOX MODE (تُنشأ المدفوعات في sandbox لدى PagBank دون أي خصومات فعلية) أو LIVE (تُنشأ المدفوعات برمز الإنتاج). وتحذّر عندما يكون رمز الوضع الحالي مفقودًا (فتُخفى طريقة الدفع عند الدفع)، وعندما لا تكون العملة الافتراضية للمتجر BRL (فلا تُعرض طريقة الدفع للسلات بعملات أخرى).

PagSeguro / PagBank

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

حساب PagBank

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

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

Sandbox token: رمز sandbox لدى PagBank. يُستخدم ما دام وضع sandbox مفعّلًا.

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

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

Clear saved tokens: ضع علامة على رمز وانقر Save لحذفه. يُبقي الحقل الفارغ القيمة المحفوظة.

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

Notification URL: كل عملية دفع تخبر PagBank إلى أين ترسل تغييرات الحالة، لذلك لا يوجد شيء يلزم إعداده في PagBank. يعرض القسم الرابط. ومع الروابط الودية يكون بالشكل التالي: https://your-shop/module/wcp_pagseguro_gateway/webhook. يجب أن يكون العنوان متاحًا من الإنترنت عبر HTTPS.

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

متقدم

Debug log: Log API requests and notifications يكتب التفاصيل في logs/wc_psg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تحتوي السجلات على رموز ولا على بيانات العملاء. تُسجَّل الأخطاء دائمًا. الافتراضي: معطّل.

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

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

عملية الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا PagSeguro / PagBank) ويؤكد. تُنشئ الوحدة عملية دفع في PagBank بإجمالي السلة بعملة BRL كعنصر واحد، باسم Order # مع رقم السلة واسم متجرك، وتوجّه العميل إلى صفحة الدفع الخاصة بـ PagBank. يُملأ اسم العميل وبريده الإلكتروني، وCPF أو CNPJ من حقل Identification number أو VAT number في العنوان، ورقم هاتف برازيلي إذا كانت هذه البيانات متوفرة لدى المتجر؛ ويمكن للعميل إكمالها أو تصحيحها في صفحة PagBank. يدفع العميل بالطرق المفعّلة في حسابك لدى PagBank، مثل بطاقة الائتمان أو PIX أو boleto. تنتهي صلاحية صفحة الدفع بعد 120 دقيقة. لا يوجد طلب في هذه المرحلة.

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

إذا لم يكتمل الدفع، يعود العميل إلى صفحة الدفع مع الرسالة The PagBank payment was not completed. You can pay the order again below. أو The PagBank payment page has expired. You can pay the order again below. أو The payment was declined by PagBank. Please try again with another card or payment method. وتبقى السلة محفوظة. وإذا أُلغي طلب كان ينتظر دفع boleto أو PIX، يرى العميل The PagBank payment was cancelled, so the order was cancelled.

عندما يدفع العميل مرة أخرى، تُعاد استخدام عملية الدفع المفتوحة في PagBank إذا كان المبلغ والبيئة نفسهما ولم تنتهِ صلاحيتها خلال 10 دقائق. وإلا تُعطَّل العملية السابقة فلا يمكن دفعها بعد ذلك. ولا تزال أي دفعة تمّت في الصفحة السابقة قبل ذلك صالحة للسلة، ويُنشأ الطلب بدلًا من دفعة جديدة.

إذا تعذّر على PagBank بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل 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. وتُكتب السبب التقني في السجل.

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

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

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى PagBank ولم يدفع، أو رُفضت البطاقة، أو انتهت صلاحية صفحة الدفع. توجد السلة فقط، ويستطيع العميل الدفع مرة أخرى.

Payment accepted: تم تأكيد الدفع بالمبلغ والعملة المتوقعين. يُسجَّل الدفع مع معرّف الشحنة لدى PagBank (charge ID) كمعرّف للمعاملة، وتعرض ملاحظة المبلغ وطريقة الدفع ومعرّف الشحنة.

Awaiting PagBank payment: تم إنشاء boleto أو PIX وهو بانتظار الدفع، أو أن الدفعة قيد التحليل. يتحول الطلب إلى Payment accepted عندما تُبلغ PagBank بأنه مدفوع.

PagBank payment on hold: أبلغت PagBank بمبلغ أو عملة مختلفين عن السلة (على سبيل المثال، عُدّلت السلة بعد إنشاء صفحة الدفع)، أو وصلت دفعة بعد إلغاء الطلب (تحقق من المخزون، ثم أكمل الطلب أو استرد الدفعة في PagBank)، أو أُذِن بدفعة بطاقة دون التقاطها (التقطها في PagBank). تشرح الملاحظة السبب. يُسجَّل المبلغ الذي تم استلامه فعليًا في الطلب.

Payment error: رُفضت دفعة كانت بانتظار الدفع أو قيد التحليل.

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

Refunded: استُرد الدفع بالكامل، عبر الوحدة أو من لوحة PagBank.

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

كتلة «PagBank payment»

تعرض صفحة الطلب كتلة PagBank payment تتضمن عملية الدفع لدى PagBank، ومعرّفات الطلب والشحنة لدى PagBank، وطريقة الدفع، والحالة، والمبلغ المدفوع والمسترد، وشارة Sandbox لمدفوعات sandbox، وسجل الاستردادات، وPagBank notes الخاصة بالطلب.

الاسترداد

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

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

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PagSeguro Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox PagSeguro Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها السطر Product: presta-payment-pagseguro والرابط 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.

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

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

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

لا تظهر PagBank عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن رمز الوضع الحالي مُدخل (Sandbox token في وضع sandbox، وProduction token في الوضع الفعلي)، وأن عملة السلة BRL. تعرض صفحة الإعدادات تحذيرًا عندما يكون الرمز مفقودًا أو عملة المتجر غير BRL. في Payment > Preferences تحقق من أن الوحدة مسموحة لعملة BRL ولدولة العميل ولمجموعة العميل.

تمت عملية الدفع لكن لم يُنشأ أي طلب: لم تُبلغ PagBank بعد عن الدفع، ولم يعد العميل إلى المتجر. يُنشأ الطلب فور وصول الإشعار. تحقق من أن متجرك متاح من الإنترنت عبر HTTPS عند Notification URL، وفعّل Debug log لمشاهدة الإشعارات.

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

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

يجيب الإشعار بـ Order not found: الإشعار يخص سلة لم تُدفع بهذه الوحدة في هذا المتجر. لا يتغير شيء.

يرى العميل الرسالة PagBank payments are temporarily unavailable. Please choose another payment method.: رمز الوضع الحالي مفقود أو رفضته PagBank.

يرى العميل الرسالة PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: السلة بعملة أخرى.

الطلب في حالة PagBank payment on hold: اقرأ الملاحظات في كتلة PagBank payment (انظر حالات الطلب)، وقارن المبالغ في PagBank، ثم أكمل الطلب أو استرد الدفعة.

يفشل الاسترداد برسالة متعلقة بالرمز: تمّت الدفعة في sandbox أو في الإنتاج، وإما أن رمز تلك البيئة مفقود أو مرفوض. أدخل الرمز الصحيح وأعد المحاولة.

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

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

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