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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

6. فعّل Enable / Disable وانقر على Save. أجرِ مدفوعات تجريبية مع تفعيل Test mode، ثم عطّله لتلقي المدفوعات الفعلية.

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting Pagar.me payment وPagar.me payment on hold. تعرض PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. ويمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Pagar.me Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. وفوق الحقول تعرض الصفحة الوضع الحالي: 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: يستخدم المفتاح السري للاختبار، ولا تُجرى أي خصومات فعلية. وما دام مفعّلًا يرى العملاء أسفل طريقة الدفع الرسالة TEST MODE — Use test credentials. No real charges.. وتستخدم فحوص حالة الطلب واستردادات الطلب دائمًا مفتاح الوضع الذي أُنشئت فيه دفعته. الافتراضي: مفعّل.

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

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

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

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

صفحة الدفع

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

Boleto due in (days): عدد الأيام حتى استحقاق boleto، من 1 إلى 30. يبقى الطلب في حالة Awaiting Pagar.me payment حتى تؤكد Pagar.me الدفع. الافتراضي: 3. وأي قيمة أخرى تُرفض عند الحفظ مع الرسالة Boleto due in (days): enter a number from 1 to 30.

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

في لوحة Pagar.me افتح Settings > Webhooks وأنشئ webhook بالرابط المعروض في Webhook URL في هذا القسم. وعند استخدام الروابط الصديقة يبدو الرابط هكذا: https://your-shop/module/wcp_pagarme_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. انسخه تمامًا كما تعرضه الإعدادات.

اختر هذه الأحداث (وهي مدرجة أيضًا في هذا القسم):

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

متقدم

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

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

Delete Data on Uninstall: عند التفعيل، تؤدي إزالة الوحدة إلى حذف إعدادات البوابة والسجل. أما الطلبات وبيانات دفع Pagar.me الخاصة بها (اللازمة للاسترداد) وحالات الطلب فتبقى محفوظة. الافتراضي: معطّل.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Pagar.me) ويؤكد. ويلزم بريد إلكتروني صالح. تُنشئ الوحدة طلب Pagar.me بإجمالي السلة بالريال البرازيلي (BRL)، مع بنود السلة والشحن وتغليف الهدايا (أو سطر واحد Order # يحمل رقم السلة عندما تتضمن السلة خصومات)، ثم تنقل العميل إلى صفحة الدفع الخاصة بـ Pagar.me. ولا يوجد أي طلب في متجرك في هذه المرحلة.

يُرسل اسم العميل وبريده الإلكتروني إلى Pagar.me. ويُؤخذ CPF أو CNPJ من حقل Identification number في العنوان، أو من VAT number؛ كما يُرسل رقم الهاتف المحمول البرازيلي. ولا يُرسل عنوان الفوترة إلا لعنوان برازيلي يحتوي على رمز CEP من 8 خانات وولاية. ولا تتضمن PrestaShop الولايات البرازيلية افتراضيًا، لذلك يدخل العميل العنوان عادةً في صفحة Pagar.me. ومن دون CPF أو CNPJ يدخلهما العميل هناك أيضًا.

بعد الدفع يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Pagar.me ذلك: إذ يقرأ المتجر طلب Pagar.me من واجهة API، ويجب أن يطابق المبلغ المدفوع والعملة السلة. وينشئ الدفع الناجح بالبطاقة أو PIX أو boleto الطلب في حالة Payment accepted، ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with Pagar.me has been received. وينشئ PIX أو boleto صادر لم يُدفع بعد الطلب في حالة Awaiting Pagar.me payment، وتعرض الصفحة الرسالة Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. وتُعاد قراءة طلب Pagar.me عند كل عودة لاحقة، لذا يُطبَّق PIX أو boleto الذي يُدفع في هذه الأثناء حتى إن لم يصل الـ webhook. وإذا فشل دفع هذا الطلب أو انتهت صلاحيته، تعرض الصفحة الرسالة Your Pagar.me payment was not completed. Please contact us about this 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. وتبقى السلة محفوظة. وإذا كان الطلب موجودًا وفشل دفعه أو انتهت صلاحيته، تكون الرسالة The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. وإذا تعذر الوصول إلى Pagar.me، تظهر صفحة Payment confirmation تطلب من العميل عدم الدفع مرة أخرى، وتعرض Check again وBack to checkout.

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

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

يعمل الـ webhook أثناء وجود المتجر في وضع الصيانة، ولا يتأثر بقيود الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Pagar.me ولم يدفع بعد، ولم يُصدر PIX أو boleto. لا توجد إلا السلة.

Payment accepted: تم تأكيد الدفع. ويُسجَّل الدفع بمعرّف طلب Pagar.me (or_...) كمعرّف للمعاملة، وتعرض ملاحظة طلب Pagar.me وطريقة الدفع.

Awaiting Pagar.me payment: صدر PIX أو boleto (أو أن دفعة البطاقة قيد المراجعة) وهو ينتظر الدفع. ينتقل الطلب إلى Payment accepted عندما تؤكد Pagar.me الدفع.

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

Payment error: فشل دفع طلب في الانتظار أو محجوز، أو أُلغي طلب Pagar.me الخاص به أو انتهت صلاحيته (مثلًا boleto غير مدفوع). وإذا أبلغت Pagar.me عن دفعة لاحقًا، ينتقل الطلب مع ذلك إلى Payment accepted.

Refunded: استُرد الدفع بالكامل عبر الوحدة، أو استُرد أو أُلغي في Pagar.me.

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

كتلة الدفع في Pagar.me

تعرض صفحة الطلب كتلة Pagar.me payment تتضمن معرّف طلب Pagar.me ومعرّفات الرسوم وطريقة الدفع والحالة والمبلغ المدفوع والمسترد، وشارة Test mode للمدفوعات التجريبية، وسجل الاستردادات، وPagar.me notes الخاصة بالطلب.

الاستردادات

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

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

لا تُنشئ الوحدة إشعارات دائنة (credit slips). ولا تعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Pagar.me.

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

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

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

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

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

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

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

تمت عملية الدفع لكن لم يُنشأ أي طلب، أو بقي الطلب في Awaiting Pagar.me payment: الـ webhook لا يعمل. في لوحة Pagar.me تحقّق من وجود الـ webhook للحساب والوضع اللذين تستخدمهما، ومن أن رابطه مطابق تمامًا للرابط المعروض في Webhook URL، ومن تحديد الأحداث المذكورة أعلاه. ويُفحص الطلب أيضًا في كل مرة يعود فيها العميل إلى المتجر.

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

يرد الـ webhook بـ busy: كانت السلة تُحدَّث بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة). وستعيد Pagar.me محاولة الـ webhook. فعّل Debug log لمعرفة السبب.

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

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

يرى العميل Pagar.me could not start the payment: رفضت Pagar.me بيانات الفوترة، مثل CPF في حقل Identification number بالعنوان. وتوضح الرسالة المشكلة؛ أما السبب الكامل فهو في السجل.

يرى العميل Pagar.me only supports payments in Brazilian Real (BRL): السلة بعملة أخرى.

يرى العميل This order already has a Pagar.me payment that the store has to review: دفعة سابقة للسلة تحتاج إلى مراجعتك. تحقّق من لوحة Pagar.me والسجل.

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

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

يفشل الاسترداد برسالة تتعلق بالوضع: تمت الدفعة في وضع الاختبار أو التشغيل، والمفتاح السري لذلك الوضع غير مضبوط. أدخله ثم أعد المحاولة.

يمكن للمطورين تغيير بيانات طلب Pagar.me قبل إرسالها باستخدام الخطاف actionWcpPagarmeOrderData.

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

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

Pagar.me علامة تجارية تعود ملكيتها إلى مالكها. هذه الوحدة غير تابعة لـ Pagar.me ولا معتمدة من قِبلها.