VibeFox dLocal for OpenCart — المساعدة

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعده (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

حساب dLocal Go: تحتاج إلى مفتاح API والسر (API secret) لحساب dLocal Go الخاص بك، وتجدهما في صفحة Payment integration ضمن لوحة تحكم dLocal Go: dashboard-sbx.dlocalgo.com لبيئة الاختبار (sandbox)، وdashboard.dlocalgo.com للإنتاج. تستخدم بيئة الاختبار وبيئة الإنتاج بيانات اعتماد مختلفة. تعمل الإضافة مع dLocal Go فقط، وليس مع واجهة dLocal Payments البرمجية للمؤسسات.

العملات والدول: لا تقيّد الإضافة العملات أو الدول. يحدد dLocal Go طرق الدفع التي يعرضها بحسب دولة العميل وعملة الطلب، وفقًا لحسابك في dLocal Go.

متجر قابل للوصول: يرسل dLocal Go إشعارات الدفع والاسترداد من خوادمه الخاصة، لذلك يجب أن تكون عناوين URL للإشعارات متاحة من الإنترنت عبر HTTPS.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل مفتاح API والسر الخاص به لبيئة الاختبار، وكذلك لبيئة الإنتاج عند تنفيذ المدفوعات الحقيقية. اختر Environment (انظر الإعدادات).

5. فعّل Enable/Disable وانقر على Save. أجرِ دفعة تجريبية في بيئة الاختبار، ثم غيّر Environment إلى Production.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص وبيانات اعتماد dLocal Go واختبر الدفع كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. عناوين URL للإشعارات فقط مختلفة (انظر Notifications (IPN)).

لا حاجة إلى إعداد أي شيء في لوحة تحكم dLocal Go: تُرسل عناوين URL للإشعارات والعودة مع كل دفعة وكل استرداد. تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة وبيئة الاختبار محددة.

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox dLocal Payment > Edit. تُدرج الأقسام على اليسار؛ ويحفظ الزر Save أسفل القائمة الصفحة بأكملها. وإلى أن تُدخل مفتاح API والسر الخاصين بالبيئة المحددة، تحذّرك الصفحة من أن طريقة الدفع مخفية في الدفع، على سبيل المثال: Enter the sandbox API key and secret: until then the payment method is hidden at checkout. (أدخل مفتاح API والسر الخاصين ببيئة الاختبار: حتى ذلك الحين تكون طريقة الدفع مخفية في صفحة الدفع.) وعند تحديد بيئة الاختبار وتفعيل طريقة الدفع، تظهر الرسالة Sandbox mode is active: payments are simulated, no money is charged. (وضع الاختبار مفعّل: تُحاكى المدفوعات ولا يُخصم أي مبلغ.) وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

عند الحفظ، يجب ألا يكون حقل Title فارغًا ولا يتجاوز 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total عددًا أكبر من 0 أو يساويه، ويجب أن توجد المنطقة الجغرافية وحالات الطلب. وإلا فلن يُحفظ شيء وتعرض الصفحة الخطأ. وإذا فُعّلت طريقة الدفع دون مفتاح وسر البيئة المحددة، تُحفظ الإعدادات مع التحذير أعلاه.

dLocal Go

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: dLocal Go. حقل إلزامي.

Description: النص الذي يظهر للعميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: ادفع بالبطاقات المحلية أو بالتحويل البنكي أو نقدًا عبر dLocal Go.

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

Geo Zone: اعرض dLocal Go فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي سلة الشراء، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب حتى يُعرض dLocal Go. اتركه فارغًا لعرض dLocal Go مهما كان المبلغ.

بيانات اعتماد API

انسخ مفتاح API والسر من لوحة تحكم dLocal Go، في قسم Payment integration: dashboard-sbx.dlocalgo.com (بيئة الاختبار) أو dashboard.dlocalgo.com (الإنتاج). يتضمن القسم روابط للوحتي التحكم كلتيهما.

Environment: بيانات الاعتماد وخوادم dLocal Go المستخدمة للمدفوعات الجديدة.

تستخدم الاستردادات وإشعارات الدفعة دائمًا بيانات اعتماد البيئة التي تمت فيها الدفعة، لذلك احتفظ ببيانات اعتماد البيئة الأخرى ما دامت مدفوعاتها لا تزال مفتوحة أو قد تحتاج إلى استرداد.

Sandbox API Key: مفتاح API الخاص ببيئة اختبار dLocal Go.

Sandbox API Secret: السر الخاص بـ API ببيئة اختبار dLocal Go.

Production API Key: مفتاح API الخاص ببيئة الإنتاج في dLocal Go.

Production API Secret: السر الخاص بـ API ببيئة الإنتاج في dLocal Go.

لا تُعرض المفاتيح والأسرار المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. (محفوظ — اتركه فارغًا للاحتفاظ به.) لا تُدخل قيمة جديدة إلا عند الرغبة في تغييرها. ولحذف قيمة محفوظة، ضع علامة على Clear the saved value أسفل الحقل، ثم انقر على Save.

الدفع

Default country: يعرض dLocal Go طرق الدفع الخاصة بدولة العميل، وتُؤخذ الدولة من عنوان الدفع، ثم من عنوان الشحن. وتُستخدم هذه الدولة عندما لا يحتوي الطلب على أي منهما. وتعرض القائمة دول متجرك. الافتراضي: Uruguay.

Auto-complete orders: يمنح الطلبات المدفوعة Complete Order Status بدلًا من Paid Order Status. الافتراضي: معطّل.

Notifications (IPN): تُخبر الإشعارات متجرك بأن دفعة أو استردادًا قد تغيّر. ترسل الإضافة عناوين URL للإشعارات إلى dLocal Go مع كل دفعة وكل استرداد، لذلك لا حاجة إلى ضبط أي شيء في لوحة تحكم dLocal Go. يعرض هذا الحقل العنوانين، وقد بُنيا من عنوان الواجهة لتثبيت OpenCart لديك:

تُتحقق الإشعارات باستخدام السر الخاص بـ API (HMAC-SHA256). تُرفض الإشعارات التي لا تحمل توقيعًا صالحًا. ويجب أن يكون الإشعار موقّعًا ببيانات اعتماد البيئة التي تمت فيها الدفعة. وبعد ذلك تُقرأ حالة الدفعة ومبلغها وعملتها دائمًا من واجهة dLocal Go البرمجية؛ ولا يُعتمد على محتوى الإشعار. وبدون الإشعارات، لا يحصل الطلب على حالته إلا عندما يعود العميل إلى المتجر.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن يؤكد dLocal Go الدفعة. يسرد كل حقل أدناه حالات الطلب في OpenCart لديك.

Paid Order Status: حالة الطلب بعد تأكيد الدفعة. الافتراضي: قيد التنفيذ.

Complete Order Status: حالة الطلب بعد تأكيد الدفعة عندما يكون Auto-complete orders مفعّلًا. الافتراضي: مكتمل.

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

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

متقدم

Debug log: يكتب طلبات dLocal Go وإشعاراته في الملف dlocal_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُنقل إلى ملف نسخة احتياطية. لا تُسجَّل بيانات الاعتماد الخاصة بـ API ولا البيانات الشخصية. تُكتب الأخطاء والتحذيرات دائمًا، أما بقية المدخلات فتُكتب فقط عندما يكون هذا الخيار مفعّلًا. الافتراضي: معطّل.

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا dLocal Go). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the dLocal Go checkout page. (سيتم تحويلك إلى صفحة الدفع الخاصة بـ dLocal Go.) وفي وضع الاختبار تظهر أيضًا الرسالة Sandbox mode: no real payment is made. (وضع الاختبار: لا تُجرى أي دفعة حقيقية.) ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة دفعة dLocal Go بإجمالي الطلب بعملة الطلب، مع دولة العميل واسمه وبريده الإلكتروني ورقم هاتفه، وترسل العميل إلى صفحة دفع dLocal Go. وهناك يدفع العميل بطريقة من بلده. وتظهر الدفعة في صفحة dLocal Go بالصيغة Order # مع رقم الطلب. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع. وإذا لم يطلب المتجر عنوان دفع (وهو الإعداد الافتراضي في OpenCart 4)، تُؤخذ دولة عنوان الشحن واسم العميل.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد dLocal Go ذلك: إما بالإشعار الموقّع، أو بطلب من جهة الخادم إلى واجهة dLocal Go البرمجية عندما يعود العميل. يتضمن عنوان العودة رمزًا عشوائيًا لمحاولة الدفع. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your payment with dLocal Go has been received. (تم استلام دفعتك عبر dLocal Go.) وإذا وُضع الطلب في حالة المراجعة، تعرض الصفحة Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. (تم استلام دفعتك عبر dLocal Go، وهي قيد مراجعة المتجر. سنخبرك عند تأكيد طلبك.) وإذا لم يؤكد dLocal Go الدفعة بعد (مثلًا قسيمة نقدية لم تُدفع بعد، أو تعذّر الوصول إلى dLocal Go)، فإن صفحة Payment confirmation تطلب من العميل ألا يدفع مرة أخرى، وتعرض Check again وBack to checkout. ويحصل الطلب على حالته فور تأكيد dLocal Go للدفعة. وفي OpenCart 4 لا يرسل المتصفح جلسة المتجر عندما يعيد dLocal Go العميل، لذلك تعرض الإضافة أولًا صفحة قصيرة تفتح عنوان العودة نفسه من متجرك مرة أخرى: يحتفظ العميل بالسلة وبتسجيل الدخول.

إذا غادر العميل صفحة dLocal Go دون الدفع، يعود إلى صفحة الدفع ويرى The payment at dLocal Go was not completed. You can try again or choose another payment method. (لم تكتمل الدفعة عبر dLocal Go. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.) وإذا رُفضت الدفعة أو انتهت صلاحيتها، فالرسالة هي Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. (لم تكتمل دفعتك عبر dLocal: تم رفضها أو انتهت صلاحيتها. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.) وفي OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع. وتبقى السلة محفوظة. وكل نقرة على Confirm Order تنشئ دفعة جديدة في dLocal Go. ويُنشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، بينما يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، فتنتمي الدفعة الجديدة إلى الطلب نفسه. ويمكن أن تظل رابط الدفع الأقدم قابلًا للدفع، فيؤكد طلبه. قبل بدء دفعة جديدة، تُقرأ من dLocal Go الدفعات المفتوحة لنفس الطلب ولنفس جلسة العميل (آخر 24 ساعة): فإذا كانت إحداها مدفوعة، تُؤكَّد طلبها ويُنقل العميل إلى صفحة النجاح دون دفعة ثانية.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا أُلغي أو استُرد)، فإن Confirm Order أو العودة من dLocal Go يعيد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، وتؤدي النقرة التالية على Confirm Order إلى دفع طلب جديد للسلة.

إذا تعذّر على dLocal Go بدء الدفعة، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة، مثل dLocal could not start the payment: متبوعة بالسبب الذي ذكره dLocal. ويحدث ذلك أيضًا عندما لا تكون دولة العميل وعملة الطلب مفعّلتين في حسابك لدى dLocal Go. وإذا رفض dLocal Go بيانات الاعتماد الخاصة بك، يرى العميل This payment method is temporarily unavailable. Please choose another payment method or contact us. (طريقة الدفع هذه غير متاحة مؤقتًا. يرجى اختيار طريقة دفع أخرى أو الاتصال بنا.) ويُكتب السبب التقني في السجل.

تعمل الإشعارات أيضًا أثناء وضع الصيانة للمتجر: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، ويضيف الإضافة في OpenCart 4 إجراء بدء تشغيل (startup action) يسمح للإشعارات وعودة العميل بالمرور.

تقبل الإضافة المدفوعات لمرة واحدة في صفحة dLocal Go فقط. ليس لديها نموذج بطاقة على موقعك، ولا بطاقات محفوظة، ولا اشتراكات، ولا تفويض وتحصيل منفصلان.

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى dLocal Go ولم يدفع، أو رُفضت الدفعة أو انتهت صلاحيتها، أو لا تزال معلّقة لدى dLocal Go. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Paid Order Status (الافتراضي قيد التنفيذ) أو Complete Order Status (الافتراضي مكتمل): تم تأكيد الدفعة. يحصل الطلب على Complete Order Status عندما يكون Auto-complete orders مفعّلًا. وتعرض ملاحظة البيئة ومعرّف دفعة dLocal.

On Hold (Review) Status (الافتراضي في انتظار الدفع): أبلغ dLocal Go عن مبلغ أو عملة تختلف عن إجمالي الطلب، أو وصلت الدفعة بعد إلغاء الطلب. وتشرح الملاحظة السبب. تحقق من لوحة تحكم dLocal Go، ثم نفّذ الطلب أو استرد الدفعة.

Refunded Status (الافتراضي مسترد): استُردت الدفعة بالكامل عبر الإضافة.

لا تغيّر الدفعة المرفوضة أو المنتهية أو الملغاة أبدًا طلبًا لديه حالة بالفعل. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب، وتطلب منك ملاحظة استرداد الدفعة المكررة في لوحة تحكم dLocal Go. ونفس النوع من الملاحظة يُضاف إلى الطلب المدفوع عندما تُدفع السلة نفسها (نفس جلسة العميل ونفس محتوى السلة) مرة أخرى مع طلب آخر، مثلًا في تبويب متصفح ثانٍ؛ وذلك الطلب الآخر لا يحصل على أي حالة.

الملاحظات هي مدخلات في History الطلب لا يراها العميل.

تبويب VibeFox dLocal Payment

في Sales > Orders افتح طلبًا دُفع عبر dLocal Go. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox dLocal Payment الحقل Payment ID وEnvironment (بيئة الاختبار أو الإنتاج) وStatus الدفعة والمبالغ Paid / refunded ونموذج الاسترداد وسجل الاستردادات وdLocal Go notes الخاصة بالطلب. ويظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox dLocal Payment أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via dLocal Go. أكّد السؤال Refund this amount through dLocal Go? This cannot be undone. (هل تريد استرداد هذا المبلغ عبر dLocal Go؟ لا يمكن التراجع عن هذا الإجراء.) الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). تُنفَّذ الاستردادات بالمبلغ والعملة اللذين خصمهما dLocal Go، لذلك بعد اختلاف في المبلغ أو العملة يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. يُرسل الاسترداد إلى البيئة التي تمت فيها الدفعة، باستخدام بيانات اعتماد تلك البيئة. وإذا لم يقبل dLocal Go الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد المقبول إلى سجل الاستردادات والملاحظات مع معرّف الاسترداد وحالته وسببه. يضع الاسترداد الكامل الطلب في Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا كتغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. وتكون الاستردادات متاحة بعد أن يؤكد dLocal Go الدفعة.

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

لا تُعيد المرتجعات من المنتجات في Sales > Returns أي أموال عبر dLocal Go. ولا تُسجَّل الاستردادات التي تُجرى في لوحة تحكم dLocal Go كاستردادات في OpenCart. حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

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

لا يظهر dLocal Go في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاح API والسر الخاص بـ Environment المحدد مضبوطان. تعرض صفحة الإعدادات تحذيرًا إذا كانا مفقودين. وتحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت الدفعة، لكن الطلب بقي بلا حالة: تعذّر على dLocal Go الوصول إلى عنوان URL للإشعار (جدار حماية، أو مصادقة أساسية، أو عدم وجود عنوان HTTPS عام)، ولم يعد العميل إلى المتجر. فعّل Debug log، وراجع الحقل Log، وتحقق من الدفعة في لوحة تحكم dLocal Go. وبمجرد وصول إشعار أو نقر العميل على Check again، يحصل الطلب على حالته.

يرد الإشعار بـ Missing signature أو Invalid signature: مفتاح API والسر في الإعدادات لا يخصان الحساب الذي أرسل الإشعار. تُتحقق الإشعارات ببيانات اعتماد بيئة الدفعة، لذلك تظل الدفعات التي بدأت قبل تغيير Environment مؤكدة، ما دامت بيانات اعتماد بيئتها موجودة في الإعدادات.

يرد الإشعار بـ Gateway not configured: بيانات اعتماد بيئة الدفعة مفقودة. أدخلها؛ وسيعيد dLocal Go إرسال الإشعار.

يرد الإشعار بـ API verification failed: تعذّر الوصول إلى واجهة dLocal Go البرمجية لقراءة الدفعة. سيعيد dLocal Go إرسال الإشعار.

يرد الإشعار بـ Temporarily unavailable: كان الطلب يُؤكَّد بطلب آخر في الوقت نفسه، أو تعذّر تعيين حالة الطلب. سيعيد dLocal Go إرسال الإشعار. والسبب موجود في السجل.

يرد الإشعار بـ Order not found: الدفعة لا تنتمي إلى طلب في هذا المتجر، مثلًا لأن موقعًا آخر أنشأها بحساب dLocal Go نفسه.

يرى العميل This payment method is temporarily unavailable: رفض dLocal Go مفتاح API أو السر. تحقق من بيانات اعتماد البيئة المحددة.

يرى العميل Payment gateway is not properly configured: بيانات اعتماد البيئة المحددة مفقودة.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox dLocal Payment. كان المبلغ أو العملة المدفوعان مختلفين عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. نفّذ الطلب أو استرد الدفعة.

لا يوجد نموذج استرداد في التبويب: يوضح التبويب السبب: الدفعة غير مؤكدة بعد، أو استُردت بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة، أو بيانات اعتماد بيئة الدفعة مفقودة.

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

للمطورين: تُطلق الإضافة أحداث OpenCart التالية: dlocal_p_payment_data (طلب الدفع والطلب، قبل إنشاء الدفعة) وdlocal_p_currency_decimals (عدد المنازل العشرية للعملة).

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

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

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

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