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

المتطلبات

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

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

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

حساب dLocal Go: تحتاج إلى مفتاح API وسر API من لوحة dLocal Go، في قسم Payment integration: dashboard-sbx.dlocalgo.com للاختبار (sandbox)، وdashboard.dlocalgo.com للإنتاج. تستخدم بيئتا sandbox والإنتاج بيانات اعتماد مختلفة. واجهة dLocal Payments API للمؤسسات (بيانات اعتماد X-Login / X-Trans-Key) منتج مختلف ولا تُدعم.

البلدان والعملات: لا تحدّ الوحدة منها. تقرر dLocal Go طرق الدفع التي تُعرض لبلد العميل وعملة السلة. وتنطبق قيود الدفع في PrestaShop فقط.

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

التثبيت

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

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

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

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

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

عند التثبيت تُنشئ الوحدة حالة الطلب dLocal payment on hold. تقدّم PrestaShop وحدة دفع جديدة لجميع العملات والبلدان ومجموعات العملاء. ويمكنك تقييدها من Payment > Preferences.

الإعدادات

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

dLocal Go

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

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

Description: النص المعروض أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay with local cards, bank transfer or cash via dLocal Go.

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

انسخ مفتاح API وسر API من لوحة dLocal Go، في قسم Payment integration: dashboard-sbx.dlocalgo.com (sandbox) أو dashboard.dlocalgo.com (production). يحتوي القسم على روابط إلى اللوحتين.

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

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

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

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

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

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

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

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

الدفع

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

Auto-complete orders: يضبط الطلبات المدفوعة على Delivered بدلًا من Payment accepted. تُضبط الحالة فورًا بتغيير واحد للحالة. الافتراضي: معطّل.

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

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

متقدم

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

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

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

صفحة الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا dLocal Go). في وضع sandbox تعرض صفحة الدفع Sandbox mode: no real payment is made. أسفل طريقة الدفع. بعد التأكيد تُنشئ الوحدة دفعة dLocal Go بإجمالي السلة وبعملة السلة، مع بلد العميل واسمه وبريده الإلكتروني ورقم هاتفه، وتُرسل العميل إلى صفحة الدفع في dLocal Go. هناك يدفع العميل بطريقة من بلده. تظهر الدفعة في صفحة dLocal Go بالصيغة Order # ورقم السلة. لا يوجد طلب في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد dLocal Go: إما بالإشعار الموقّع، أو بطلب من الخادم إلى واجهة dLocal Go API عند عودة العميل. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة مع Your payment with dLocal Go has been received. وإذا وُضع الطلب في حالة التعليق، تعرض الصفحة 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)، تطلب صفحة Payment confirmation من العميل ألّا يدفع مرة أخرى، وتعرض Check again وBack to checkout. يُنشأ الطلب فور تأكيد dLocal Go للدفعة.

إذا غادر العميل صفحة dLocal Go دون أن يدفع، يعود إلى صفحة الدفع ويرى The payment at dLocal Go was not completed. You can try again or choose another payment method. وإذا رُفضت الدفعة أو انتهت صلاحيتها، تكون الرسالة Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. تبقى السلة محفوظة. كل محاولة جديدة تُنشئ دفعة dLocal Go جديدة، ويظل رابط الدفع الأقدم لنفس السلة قابلًا للدفع ويُنشئ الطلب.

إذا تعذّر على dLocal Go بدء الدفعة، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل 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. ويُكتب السبب التقني في السجل.

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

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

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى dLocal Go ولم يدفع، أو أن الدفعة لا تزال معلّقة في dLocal Go. لا توجد سوى السلة.

Payment accepted or Delivered: تم تأكيد الدفعة. يصبح الطلب بحالة «تم قبول الدفع» أو، عند تفعيل Auto-complete orders، بحالة «تم التسليم». تُسجَّل الدفعة بمعرّف دفعة dLocal كمعرّف للمعاملة، وتعرض ملاحظة البيئة ومعرّف الدفعة.

dLocal payment on hold: أبلغت dLocal Go عن مبلغ أو عملة يختلفان عن إجمالي السلة (مثلًا تغيّرت السلة في تبويب آخر بعد بدء الدفع)، أو وصلت الدفعة بعد إلغاء الطلب. تشرح الملاحظة السبب. قارن ذلك بلوحة dLocal Go، ثم أكمل الطلب أو استرد الدفعة.

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

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

كتلة الدفع في dLocal Go

تعرض صفحة الطلب كتلة dLocal Go payment تتضمن معرّف دفعة dLocal، والبيئة (مع شارة Sandbox لدفعات الاختبار)، وحالة الدفعة، والمبلغ الذي حصّلته dLocal Go والمبلغ المسترد، ونموذج الاسترداد، وسجل الاسترداد، وdLocal Go notes الخاصة بالطلب.

الاسترداد

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

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

لا تُنشئ الوحدة إشعارات دائن (credit slip). أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترسل المال عبر dLocal Go. والاستردادات التي تُجرى في لوحة dLocal Go لا تُسجَّل كاستردادات في PrestaShop، ولا تضيف عادة أي ملاحظة. حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

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

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

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

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

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

يرد الإشعار بـ API verification failed: تعذّر الوصول إلى واجهة dLocal Go API لقراءة الدفعة. وستعيد 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: بيانات اعتماد البيئة المختارة مفقودة.

الطلب في حالة dLocal payment on hold بعد الدفع: اقرأ الملاحظات في كتلة dLocal Go payment. كان المبلغ أو العملة المدفوعان مختلفين عن السلة، أو وصلت الدفعة بعد إلغاء الطلب. أكمل الطلب أو استرد الدفعة.

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

للمطوّرين: توثّق الوحدة الخطافين actionWcpDlocalPaymentData وactionWcpDlocalCurrencyDecimals.

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

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

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