VibeFox Pagar.me 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 ويكون إجمالي الطلب أكبر من صفر.

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

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

التثبيت

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

OpenCart 3

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

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

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

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

5. أنشئ ويبهوك في لوحة تحكم Pagar.me بالرابط الظاهر في الإعدادات (راجع الإعداد).

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

OpenCart 4

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

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

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

4. الصق مفتاح الترخيص والمفاتيح السرية، واضبط الويبهوك كما في الخطوات من 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الرابط الخاص بالويبهوك فقط مختلف (انظر إشعارات الدفع (ويبهوك)).

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

الإعداد

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

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

Pagar.me

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Pagar.me. حقل إلزامي، حتى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order، أعلى زر التأكيد. الافتراضي: ادفع بأمان عبر Pagar.me (بطاقة ائتمان أو PIX أو boleto). سيتم توجيهك لإكمال الدفع.

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

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

Total: إجمالي الشراء، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض Pagar.me. اتركه فارغًا لعرض Pagar.me مهما كان الإجمالي.

مفاتيح API

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

Test mode: يستخدم المفتاح السري للاختبار، ولا يتم أي خصم فعلي. وعند تفعيله، يرى العملاء في خطوة Confirm Order العبارة 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 the saved key on save أسفل الحقل، ثم انقر على Save.

صفحة الدفع

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

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

إشعارات الدفع (ويبهوك)

في لوحة تحكم Pagar.me، افتح Settings > Webhooks وأنشئ ويبهوك بالرابط الظاهر في Webhook URL ضمن هذا القسم. في OpenCart 3 يبدو الرابط كالتالي: https://your-store/index.php?route=extension/payment/wcp_pagarme_gateway/webhook، وفي OpenCart 4 كالتالي: https://your-store/index.php?route=extension/wcp_pagarme_gateway/payment/wcp_pagarme_gateway.webhook. ويُبنى من عنوان واجهة متجر تثبيت OpenCart الخاص بك. انسخه تمامًا كما تعرضه الإعدادات. يجب أن يكون الرابط متاحًا من الإنترنت.

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

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

الطلبات

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

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

Awaiting Pagar.me Payment Status: صدر رمز PIX أو boleto، أو أن دفعة البطاقة قيد التحليل؛ وسيؤكد Pagar.me استلام الأموال لاحقًا. الافتراضي: قيد الانتظار.

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

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

Cancelled Order Status: الحالة التي يستخدمها متجرك للطلبات الملغاة. لا تعيّنها الإضافة: فدفعة Pagar.me تصل بعد ذلك تنقل الطلب إلى حالة المراجعة. الافتراضي: ملغى.

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

متقدم

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

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

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

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

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

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

إتمام الشراء

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Pagar.me). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the Pagar.me payment page to pay by credit card, PIX, boleto or debit card. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order أسفل صفحة الشراء. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة طلب Pagar.me بإجمالي الطلب بعملة BRL، وتُرسل العميل إلى صفحة الدفع الخاصة بـ Pagar.me. تُرسل بنود الطلب التي تتضمن الضرائب والشحن والرسوم الإضافية الأخرى كعناصر؛ وعندما يحتوي الطلب على خصم (قسيمة أو كوبون أو نقاط مكافأة) أو لا تتطابق البنود مع الإجمالي، يُرسل بند واحد Order # يحمل رقم الطلب بالإجمالي. ويلزم بريد إلكتروني صالح.

يُمرَّر اسم العميل وبريده الإلكتروني إلى Pagar.me. ويُؤخذ رقم CPF أو CNPJ (11 أو 14 رقمًا) من حقل مخصص للعميل أو لعنوان الدفع يحتوي اسمه على CPF أو CNPJ؛ فـ OpenCart لا يملك مثل هذا الحقل افتراضيًا، لذا أضفه في Customers > Custom Fields إذا أردت تمريره. في OpenCart 4، وعندما لا يطلب المتجر عنوان الفوترة، يُستخدم عنوان الشحن وحقوله المخصصة. ويُمرَّر أيضًا رقم الهاتف المحمول البرازيلي. ولا يُمرَّر عنوان الفوترة إلا لعنوان برازيلي يتضمن رمز CEP من 8 أرقام والولاية. وإذا لم يتوفر CPF أو CNPJ، يُدخله العميل في صفحة Pagar.me.

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

وإذا عاد العميل دون أن يدفع، فإنه يعود إلى صفحة الشراء مع الرسالة The Pagar.me payment was not completed. You can try again or choose another payment method. وإذا رُفض الدفع أو أُلغي، فالرسالة هي The Pagar.me payment was declined or canceled. You can try again or choose another payment method. وتُحفظ السلة. في OpenCart 4 تظهر هذه الرسائل فوق صفحة الشراء. وإذا كان للطلب حالة بالفعل وفشل دفعه أو انتهت صلاحيته، فالرسالة هي The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. وإذا كانت السلة فارغة بالفعل (مثلًا عندما وصل الطلب إلى صفحة النجاح قبل انتهاء صلاحية PIX أو boleto الخاص به)، فلا يوجد ما يُدفع في صفحة الشراء: تقول صفحة Payment confirmation The Pagar.me 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. وإذا تعذر الوصول إلى Pagar.me، تطلب صفحة Payment confirmation من العميل ألا يدفع مرة أخرى، وتعرض Check again وBack to checkout.

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

يُبقي OpenCart 4 الطلب في صفحة الشراء حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب في هذه الأثناء (مثلًا لأن PIX أو boleto الخاص به انتهت صلاحيته، أو فشلت دفعته، أو ألغيته أو استردته)، فيُعيد Confirm Order العميل إلى صفحة الشراء مع الرسالة Your previous order was cancelled or its payment failed. Please confirm the order again.، أو، إذا كان الطلب قد دُفع قبل إغلاقه، مع الرسالة This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay.. وينشئ النقر التالي على Confirm Order طلبًا جديدًا للدفع. وعندما يعود العميل من Pagar.me إلى طلب دُفع ثم أغلقته أنت، يرى الرسالة نفسها في صفحة الشراء، أو، إذا كانت السلة فارغة بالفعل، صفحة تحمل Order #(الرقم) was closed by the store, so it will not be shipped. To buy these items, please place a new order. وإذا كان لطلب صفحة الشراء حالة بالفعل وتغيّرت المنتجات أو الكميات في السلة، يُعاد العميل إلى صفحة الشراء، وتحصل السلة الجديدة على طلب جديد.

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

يعمل الويبهوك أيضًا عندما يكون المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، أما في OpenCart 4 فتُضيف الإضافة إجراء بدء تشغيل يسمح للويبهوك وبعودة العميل من Pagar.me بالمرور.

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

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

حالات الطلب

No status (missing order): أُرسل العميل إلى Pagar.me ولم يدفع بعد أو لم يصدر PIX أو boleto، أو رُفضت الدفعة. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط فلتر Order Status على Missing Orders.

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

Order Status After Payment (default Processing): تم تأكيد الدفع. تعرض ملاحظة معرّف طلب Pagar.me (or_...) وطريقة الدفع.

Awaiting Pagar.me Payment Status (default Pending): صدر PIX أو boleto (أو أن دفعة البطاقة قيد التحليل) وهو في انتظار الدفع. ينتقل الطلب إلى Order Status After Payment عندما يؤكد Pagar.me الدفعة.

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

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

Refunded Status (default Refunded): استُرد الدفع بالكامل عبر الإضافة، أو استُرد أو أُلغي في Pagar.me.

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

علامة تبويب VibeFox Pagar.me Gateway

في Sales > Orders افتح طلبًا دُفع عبر Pagar.me. في أسفل صفحة الطلب، بجانب History وAdditional، تعرض علامة التبويب VibeFox Pagar.me Gateway معرّف Pagar.me order مع تسمية Test mode لمدفوعات الاختبار، وPayment method، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد، وPagar.me notes الخاصة بالطلب. وتُعرض علامة التبويب للمستخدمين الذين يملكون صلاحية الوصول إلى الإضافة.

الاستردادات

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

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

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

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

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

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

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

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

Pagar.me does not appear at checkout: تحقّق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن المفتاح السري للوضع الحالي مضبوط (Test secret key في وضع الاختبار، وLive secret key في وضع التشغيل الفعلي)، وأن العميل يُكمل الشراء بعملة BRL. وتعرض صفحة الإعدادات تحذيرًا عند غياب المفتاح. وتحقّق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

The payment went through, but the order stays without a status or in the awaiting status: الويبهوك لا يعمل. تحقّق في لوحة تحكم Pagar.me من وجود الويبهوك للحساب والوضع اللذين تستخدمهما، ومن أن رابطه مطابق تمامًا للرابط الظاهر في Webhook URL، ومن تحديد الأحداث المذكورة أعلاه. ويُتحقق من الطلب أيضًا في كل مرة يعود فيها العميل إلى المتجر.

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

The webhook answers busy: كانت السلة تُعالَج بواسطة طلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. ويعيد Pagar.me محاولة الويبهوك. فعّل Debug log لمعرفة السبب.

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

The webhook answers invalid payload or invalid order id: الطلب ليس إشعارًا من Pagar.me. لا يتغير شيء.

The customer sees Pagar.me payments are not available right now: المفتاح السري خاطئ أو مفقود. تحقّق من مفتاح الوضع الحالي.

The customer sees Pagar.me could not start the payment: رفض Pagar.me تفاصيل الفوترة، مثل رقم CPF في الحقل المخصص. وتذكر الرسالة المشكلة؛ أما السبب الكامل فموجود في السجل.

The customer sees A valid billing email is required for Pagar.me.: البريد الإلكتروني للطلب غير صالح.

The customer sees Pagar.me only supports payments in Brazilian Real (BRL).: صفحة الشراء بعملة أخرى.

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

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

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

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

للمطوّرين: قبل إرسال طلب Pagar.me، تُطلق الإضافة حدث OpenCart المسمى wc_pgm_order_data مع نص الطلب والطلب نفسه. ويجب أن يبقى مبلغ الدفع مساويًا لإجمالي الطلب.

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

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

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

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