VibeFox Pagar.me for WooCommerce — المساعدة

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

حساب Pagar.me: تحتاج إلى المفاتيح السرية لحساب Pagar.me: مفتاح الاختبار (sk_test_...) ومفتاح التشغيل (sk_...) عند الانتقال إلى الوضع الفعلي. وتجدهما في لوحة Pagar.me تحت Development > Keys. تُستخدم المفاتيح السرية فقط؛ ولا حاجة إلى المفتاح العام (pk_...). ولا يمكن عرض إلا طرق الدفع المفعّلة في حساب Pagar.me الخاص بك.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل المفتاح السري للاختبار، وعند الانتقال إلى الوضع الفعلي أدخل المفتاح السري للتشغيل.

6. أنشئ الـ webhook في لوحة Pagar.me بالرابط المعروض في الإعدادات (انظر الإعداد).

7. فعِّل Enable / Disable واحفظ. أجرِ مدفوعات تجريبية مع تفعيل Test mode، ثم أوقفه لقبول المدفوعات الفعلية.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Pagar.me. وتعرض الصفحة أسفل العنوان الوضع الحالي: TEST MODE (تُنشأ المدفوعات بالمفتاح السري للاختبار دون رسوم فعلية) أو LIVE. وتحذّر عندما يكون المفتاح السري للوضع الحالي مفقودًا (فتُخفى طريقة الدفع عندئذٍ في صفحة الدفع)، وعندما لا يبدأ مفتاح الاختبار بـ sk_test_، وعندما لا يبدأ مفتاح التشغيل بـ sk_ أو يكون مفتاح اختبار، وعندما لا تكون عملة المتجر BRL. وفي قائمة طرق الدفع، يظهر Pagar.me على أنه يحتاج إلى إعداد حتى يُدخل مفتاح الوضع الحالي، ويظهر شارة وضع الاختبار ما دام وضع الاختبار مفعّلًا.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: Pagar.me.

Description: النص الظاهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

مفاتيح API

انسخ المفاتيح السرية من لوحة Pagar.me: Development > Keys. تستخدم Pagar.me عنوان API واحدًا للمدفوعات التجريبية والفعلية؛ والمفتاح هو الذي يحدد ما إذا كانت الدفعة تجريبية أم فعلية.

Test mode: Use the test secret key (no real charges). ما دام وضع الاختبار مفعّلًا، تظهر عند الدفع ملاحظة TEST MODE. وتستخدم فحوص حالة الطلب والاستردادات دائمًا مفتاح الوضع الذي أُنشئت فيه دفعته. الافتراضي: مفعّل.

Test secret key: المفتاح السري للاختبار في Pagar.me (sk_test_...). ويُستخدم ما دام وضع الاختبار مفعّلًا.

Live secret key: المفتاح السري للتشغيل في Pagar.me (sk_...). ويُستخدم عندما يكون وضع الاختبار معطّلًا. احتفظ به سرًا.

يُنقل المفتاح السري الوحيد في الإصدار 1.0 تلقائيًا: يُنقل مفتاح الاختبار إلى Test secret key ويُفعَّل وضع الاختبار؛ وإلا يبقى مفتاحًا للتشغيل ويُعطَّل وضع الاختبار.

صفحة الدفع

Payment methods: الطرق المعروضة في صفحة الدفع الخاصة بـ Pagar.me. اختر فقط الطرق المفعّلة في حساب Pagar.me الخاص بك. الافتراضي: Credit card وPIX وBoleto.

Boleto due in (days): عدد الأيام حتى تاريخ استحقاق boleto، من 1 إلى 30. يبقى الطلب On hold حتى تؤكد Pagar.me الدفع. الافتراضي: 3.

إشعارات الدفع (webhook)

في لوحة Pagar.me، افتح Settings > Webhooks وأنشئ webhook بالرابط الظاهر في هذا القسم. وهو بالشكل التالي: https://your-site/wc-api/webhook_wc_pagarme/. انسخه تمامًا كما تعرضه الإعدادات.

اختر هذه الأحداث:

لا يحتاج الـ webhook إلى كلمة مرور أو توقيع. ولا يُوثق بمحتواه أبدًا: لا يأخذ المتجر منه إلا معرّف طلب Pagar.me، ويقرأ ذلك الطلب من واجهة Pagar.me API بمفتاح الوضع الذي أُنشئ فيه. ويتم تجاهل الإشعارات الخاصة بطلبات متاجر أخرى في حساب Pagar.me نفسه. وبدون الـ webhook، لا تُؤكَّد مدفوعات PIX وboleto التي تتم لاحقًا إلا عندما يعود العميل إلى المتجر.

متقدم

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

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

الدفع

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

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Pagar.me: يقرأ المتجر طلب Pagar.me من الواجهة، ويجب أن يطابق المبلغ والعملة المدفوعان الطلب. ويُعلَّم الطلب كمدفوع عند دفع البطاقة أو PIX أو boleto. أما PIX أو boleto الصادر وغير المدفوع بعد، فيبقي الطلب On hold حتى تؤكد Pagar.me الدفع عبر الـ webhook.

إذا عاد العميل دون دفع، أو رُفض الدفع أو أُلغي، ينتقل إلى صفحة Pay for order مع الرسالة The Pagar.me payment was not completed. You can pay the order below. أو The Pagar.me payment was declined or canceled. You can try again below.

عندما يدفع العميل مرة أخرى، تُعاد استخدام صفحة دفع Pagar.me المفتوحة إذا كان المبلغ والوضع متطابقين؛ وإلا تُغلق في Pagar.me قبل إنشاء صفحة جديدة. وإذا دُفعت المحاولة السابقة في غضون ذلك، أو كان PIX أو boleto الخاص بها ما زال ينتظر، يُحدَّث الطلب دون دفعة جديدة. وإذا تعذّر إغلاق الصفحة السابقة، فإنها تبقى مرتبطة بالطلب، فتُسجَّل أي دفعة تتم فيها.

إذا تعذّر على Pagar.me بدء الدفع، يرى العميل رسالة قصيرة، مثل Could not connect to Pagar.me. Please try again in a moment.، أو رسالة Pagar.me بشأن بيانات فوترة غير صالحة. ويُضاف السبب التقني إلى ملاحظات الطلب.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

لا تتضمن الإضافة نموذج بطاقة داخل صفحة الدفع، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا قواعد للتقسيط، ولا مدفوعات مجزأة (السوق الإلكتروني)، ولا مدفوعات بالبطاقة بالتفويض فقط، ولا تكاملًا مع Pagar.me Hub.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Pagar.me ولم يدفع أو يُنشئ PIX أو boleto بعد. وتعرض ملاحظة معرّف طلب Pagar.me والوضع.

Processing: تم تأكيد الدفع. وهذه الحالة القياسية في WooCommerce بعد الدفع؛ وتنتقل الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى حالة Completed. وتعرض ملاحظة الطلب معرّف طلب Pagar.me وطريقة الدفع. ومعرّف المعاملة هو معرّف طلب Pagar.me (or_...).

On hold: صدر PIX أو boleto (أو أن دفعة البطاقة قيد المراجعة) وهو ينتظر الدفع؛ أو دُفع boleto جزئيًا فقط؛ أو أن المبلغ أو العملة المدفوعين يختلفان عن الطلب؛ أو وصلت دفعة بعد إلغاء الطلب؛ أو دُفع الطلب في Pagar.me بعد أن غيّر العميل طريقة الدفع؛ أو فُتح عملية استرجاع (chargeback) على طلب مدفوع. وتشرح ملاحظة الطلب السبب. راجع الطلب واضبطه على Processing، أو استرد الدفعة في Pagar.me.

Failed: فشل الدفع، أو أُلغي طلب Pagar.me أو انتهت صلاحيته (مثل boleto غير مدفوع). ولا يمكن لغير آخر محاولة في طلب غير مدفوع أن تحوّله إلى Failed. ويمكن للعميل أن يدفع مرة أخرى.

Refunded: استُرد الدفع أو أُلغي في Pagar.me.

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

الاستردادات

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

لا يمكن استرداد مدفوعات boleto إلا إلى الحساب البنكي للعميل. استردها في لوحة Pagar.me، ثم سجّل الاسترداد يدويًا في WooCommerce دون استخدام Refund via Pagar.me.

يصل الاسترداد الكامل أو الإلغاء الذي يتم في لوحة Pagar.me عبر الـ webhook ويضبط الطلب على Refunded. وتضيف عملية الاسترجاع (chargeback) ملاحظة وتضع طلبًا في حالة Processing أو Completed على On hold.

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

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

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

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

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

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

لا يظهر Pagar.me عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن المفتاح السري للوضع الحالي مُدخل (Test secret key في وضع الاختبار، وLive secret key في وضع التشغيل)، وأن عملة المتجر هي BRL. وتعرض صفحة الإعدادات تحذيرًا في كل حالة من هذه الحالات.

تمّ الدفع لكن الطلب ما زال في Pending payment أو On hold: الـ webhook لا يعمل. في لوحة Pagar.me تحقق من وجود الـ webhook للحساب والوضع اللذين تستخدمهما، ومن أن رابطه مطابق تمامًا للرابط الظاهر في الإعدادات، ومن اختيار الأحداث المذكورة أعلاه. ويُتحقق من الطلب أيضًا عندما يعود العميل إلى المتجر.

يرد الـ webhook بـ verification failed, retry later: لم يتمكن المتجر من قراءة طلب Pagar.me من الواجهة، مثلًا لأن مفتاح ذلك الوضع مفقود أو لم تستجب الواجهة. وتعيد Pagar.me محاولة الـ webhook.

يرد الـ webhook بـ busy, retry later: كان الطلب يُحدَّث بطلب آخر في الوقت نفسه. وتعيد Pagar.me محاولة الـ webhook.

يرد الـ webhook بـ unknown order: لم يُنشئ هذا المتجر طلب Pagar.me، مثل طلب لمتجر آخر في الحساب نفسه. ولا يُغيَّر شيء.

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

يرى العميل Pagar.me payments are not available right now: المفتاح السري غير صحيح أو مفقود. تحقق من مفتاح الوضع الحالي.

يرى العميل Pagar.me could not start the payment: رفضت Pagar.me بيانات الفوترة. وتحدد الرسالة المشكلة؛ والسبب الكامل موجود في ملاحظات الطلب.

يرى العميل Pagar.me only supports payments in Brazilian Real (BRL): الطلب بعملة أخرى، مثلًا بسبب إضافة لتبديل العملات.

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

فشل الاسترداد لـ boleto: لا يمكن استرداد مدفوعات boleto عبر الواجهة. استرد من لوحة Pagar.me وسجّل الاسترداد يدويًا.

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

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

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

Pagar.me علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ Pagar.me ولا معتمدة منها.