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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل.

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

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

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

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

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

التثبيت

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

2. انقر على Activate. يجب أن يكون WooCommerce مفعّلًا.

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

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

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

6. فعّل Enable/Disable واحفظ. اختبر دفعة في بيئة الاختبار، ثم بدّل Environment إلى Production.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > dLocal Go. يعرض عنوان الصفحة SANDBOX أو PRODUCTION. وإلى أن يُدخَل مفتاح API والسر للبيئة المحددة، تحذّرك الصفحة من أن طريقة الدفع مخفية في صفحة الدفع. وما دامت بيئة الاختبار محددة والبوابة مفعّلة، تعرض الصفحة Sandbox mode is active: payments are simulated, no money is charged. وفي قائمة طرق الدفع، تظهر dLocal Go على أنها تحتاج إلى إعداد إلى أن تُضبط بيانات الاعتماد، وتعرض Test mode في بيئة الاختبار.

عام

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 (بيئة الاختبار) أو 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.

الدفع

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

Auto-complete orders: Set paid orders to "Completed" instead of "Processing". تُضبط الحالة دفعة واحدة، مع مجموعة واحدة من رسائل البريد الإلكتروني. الافتراضي: متوقف.

الإشعارات (IPN)

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

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

متقدم

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

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). الافتراضي: متوقف.

صفحة الدفع

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

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

إذا غادر العميل صفحة dLocal Go دون أن يدفع، يعود إلى صفحة الدفع (أو إلى صفحة Pay for order) ويرى 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 could not start the payment: متبوعة بالسبب الوارد من dLocal، ويمكنه اختيار طريقة أخرى. ويحدث هذا أيضًا عندما لا يكون بلد العميل وعملة المتجر مفعّلين في حساب dLocal Go الخاص بك. ويُكتب السبب التقني في السجل.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة الدفع، وفي صفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

حالات الطلب

Pending payment: حُوِّل العميل إلى dLocal Go ولم يدفع بعد، أو أن الدفعة قيد الانتظار لدى dLocal Go (مثل قسيمة دفع نقدي لم تُسدَّد بعد). تُسجَّل كل محاولة دفع جديدة في الطلب مع معرّف دفعة dLocal والمبلغ والبيئة.

Processing or Completed: تأكدت الدفعة. يكون الطلب «قيد التنفيذ» (الافتراضي في WooCommerce)، أو «مكتمل» عند تشغيل Auto-complete orders. ومعرّف المعاملة هو معرّف دفعة dLocal.

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

Failed: رُفضت آخر محاولة دفع أو انتهت صلاحيتها. يمكن للعميل المحاولة مجددًا.

Cancelled: أبلغت dLocal Go بأن آخر محاولة دفع أُلغيت.

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

الاستردادات

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

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

الاستردادات التي تُجرى في لوحة تحكم dLocal Go لا تُسجَّل كاستردادات في WooCommerce، وعادةً لا تضيف ملاحظة إلى الطلب. وعند الحاجة، أنشئ استردادًا يدويًا في WooCommerce دون Refund via dLocal Go.

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

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

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

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

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

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

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

تمت الدفعة، لكن الطلب يبقى «قيد انتظار الدفع»: لم تتمكن dLocal Go من الوصول إلى عنوان URL للإشعارات (جدار حماية، وضع الصيانة، المصادقة الأساسية)، ولم يعد العميل إلى صفحة استلام الطلب. تحقق من WooCommerce > Status > Logs، المصدر wcp_dlocal_payment، ومن الدفعة في لوحة تحكم dLocal Go. وبمجرد وصول إشعار أو فتح العميل صفحة استلام الطلب، يُحدَّث الطلب.

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

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

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

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

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

الطلب «معلّق» بعد الدفع: اقرأ ملاحظة الطلب. اختلف المبلغ أو العملة المدفوعة عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. نفّذ الطلب أو استرد الدفعة.

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

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

للمطورين، تسرد وثائق الإضافة المرشحات dlocal_p_payment_data وdlocal_p_currency_decimals وdlocal_p_icon.

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

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

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