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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

العملة: الريال البرازيلي (BRL). يُخفى طريقة الدفع عند الدفع إذا كانت عملة المتجر (أو عملة الطلب في صفحة Pay for order) ليست BRL.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل Enable / Disable واحفظ. أجرِ مدفوعات تجريبية مع تفعيل Sandbox Mode، ثم عطّله لقبول المدفوعات الحقيقية.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > PagSeguro / PagBank. تعرض الصفحة أسفل العنوان الوضع الحالي: SANDBOX MODE (تُنشأ المدفوعات في sandbox لدى PagBank دون أي خصم فعلي) أو LIVE (تُنشأ المدفوعات برمز الإنتاج). وتُحذّر إذا كان رمز الوضع الحالي مفقودًا (وفي هذه الحالة تُخفى طريقة الدفع عند الدفع)، وإذا كانت عملة المتجر ليست BRL. وفي قائمة طرق الدفع يُعرض PagBank على أنه بحاجة إلى إعداد إلى أن يُدخل رمز الوضع الحالي، ويظهر شارة وضع الاختبار طالما كان وضع sandbox مفعّلًا.

عام

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. تستخدم عمليات الاستعلام عن الحالة والاسترداد الخاصة بالطلب دائمًا البيئة والرمز اللذين أُنشئت بهما دفعته. الافتراضي: مفعّل.

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

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

يُنقل الرمز الواحد من الإصدار 1.0 تلقائيًا: إذا كان وضع sandbox مفعّلًا فيصبح رمز sandbox، وإلا فيبقى رمز الإنتاج.

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

كل عملية دفع تُخبر PagBank بالجهة التي يجب إرسال تغييرات الحالة إليها، لذلك لا يلزم إعداد شيء في PagBank. يعرض هذا القسم عنوان URL للإشعارات، وهو بالشكل التالي: https://your-site/wc-api/webhook_wc_pagseguro/. يجب أن يكون العنوان متاحًا من الإنترنت عبر HTTPS.

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

متقدم

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

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

الدفع

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

تنتهي صلاحية صفحة الدفع قبل 5 دقائق من إلغاء مؤقت Hold stock في WooCommerce للطلب غير المدفوع (10 دقائق على الأقل)، أو بعد 120 دقيقة إذا لم يُحجز المخزون.

بعد الدفع يعود العميل إلى المتجر. تُتحقق هذه العودة بالطريقة نفسها التي يُتحقق بها الإشعار: تقرأ الإضافة الدفعة من واجهة PagBank البرمجية، ولا تُعلِّم العودة وحدها أي طلب كمدفوع أبدًا. يُنقل الطلب المدفوع، أو الدفع المعلّق (boleto وPIX والتحليل)، إلى صفحة استلام الطلب؛ ويُؤكَّد الطلب بالإشعار إذا لم تكن PagBank قد أرسلته بعد.

إذا لم يكتمل الدفع، يعود العميل إلى صفحة Pay for order مع الرسائل 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. وإذا أُلغي الدفع والطلب معه، ينتقل العميل إلى السلة مع الرسالة 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 إلى ملاحظات الطلب.

تعمل طريقة الدفع في الدفع الكلاسيكي وفي كتلة Checkout وفي صفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى PagBank ولم يدفع بعد. تُظهر ملاحظة معرّف عملية الدفع لدى PagBank والبيئة. إذا انتهت صلاحية صفحة الدفع دون دفع، تُشير ملاحظة إلى ذلك ولا تتغير الحالة.

Processing: تم تأكيد الدفع. هذه هي الحالة القياسية في WooCommerce بعد الدفع؛ وتصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط مكتملة. تُظهر ملاحظة الطلب المبلغ وطريقة الدفع ومعرّف الخصم لدى PagBank، وهو أيضًا معرّف المعاملة للطلب.

On hold: تم إنشاء boleto أو PIX وهو بانتظار الدفع؛ أو الدفع قيد التحليل؛ أو دفعة بالبطاقة جرى تفويضها دون تحصيل (حصّلها في PagBank)؛ أو المبلغ المدفوع أو العملة لا يتطابقان مع الطلب؛ أو وصلت دفعة بعد أن ألغى WooCommerce الطلب غير المدفوع (تحقّق من المخزون، ثم أكمل الطلب أو استرد الدفعة في PagBank). تشرح ملاحظة الطلب السبب.

Failed: رُفض الدفع. يمكن للعميل إعادة الدفع من صفحة Pay for order.

Cancelled: أُلغي الدفع، مثل boleto أو PIX منتهي الصلاحية.

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

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

الاسترداد

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

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

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

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

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

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

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

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

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

تم الدفع لكن الطلب بقي في حالة «في انتظار الدفع»: لم تُبلغ PagBank بالدفع بعد، ولم يعد العميل إلى المتجر. يُحدَّث الطلب فور وصول الإشعار. تحقق من أن موقعك متاح من الإنترنت عبر HTTPS، وراجع WooCommerce > Status > Logs، بمصدر wcp_pagseguro_gateway.

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

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

يرد الإشعار بـ Order not found: الطلب غير موجود في هذا المتجر، أو دُفع بطريقة دفع أخرى. لا يتغير شيء.

يرى العميل This order is already being processed: كان إشعار أو عودة العميل يُحدّثان الطلب في اللحظة نفسها. يمكن للعميل المحاولة مرة أخرى بعد لحظات.

يرى العميل PagBank payments are temporarily unavailable: رمز الوضع الحالي مفقود، أو رفضته PagBank.

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

الطلب في حالة On hold مع الملاحظة Amount/currency does not match: أبلغت PagBank عن دفعة يختلف مبلغها أو عملتها عن إجمالي الطلب، مثلًا لأن الطلب عُدِّل بعد إنشاء صفحة الدفع. قارن المبالغ في PagBank، ثم أكمل الطلب أو استرده يدويًا.

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

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

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

يُبقي تعطيل الإضافة جميع البيانات كما هي. لإزالتها، عطّلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص الخاصان بهذه الإضافة دائمًا. أما إعدادات البوابة وخياراتها الأخرى وسجلاتها فلا تُحذف إلا إذا كان Delete Data on Uninstall مفعّلًا؛ وإلا تبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات وبيانات PagBank.

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