بوابة دفع Mercado Pago Terminal
تتيح لك بوابة دفع Mercado Pago Terminal قبول المدفوعات الحضورية على أجهزة Mercado Pago Point Smart الطرفية عبر WCPOS. يبدأ الدفع من WooCommerce ويكتمل على الجهاز الطرفي، ثم يُسجَّل تأكيد Mercado Pago في الطلب.
Mercado Pago Terminal for WooCommerce إضافة جديدة، والإصدار 0.1.0 هو إصدارها الأول. تعامل معها كإصدار تجريبي: ابدأ بوضع Test باستخدام الجهاز الافتراضي التجريبي من Mercado Pago، ونفّذ دفعة اختبار قبل قبول مدفوعات حقيقية.
الميزات
أجهزة Point Smart
قبول المدفوعات الحضورية على أجهزة Mercado Pago Point Smart 1 و2 الطرفية
قائمة الأجهزة الطرفية المباشرة
تُجلب الأجهزة الطرفية مباشرةً من حسابك، مع إجراء للتبديل إلى PDV بنقرة واحدة في الإعدادات
إتمام موثوق
يؤكد المدفوعاتِ الاستطلاعُ كل 2 ثانية، وخطاف الويب من Mercado Pago، وفحصٌ في الخلفية بعد 5 دقائق، حتى إذا أُغلق المتصفح
المبالغ المستردة من WooCommerce
إجراء استرداد كامل أو جزئي من شاشة طلب WooCommerce
تشخيص مدمج
تحقق من الاتصال وحالة خطاف الويب في الإعدادات، ونزّل حزمة دعم لاستكشاف الأخطاء وإصلاحها
آلية العمل
تستخدم بوابة الدفع Orders API for Point السحابية من Mercado Pago. يؤدي بدء الدفع إلى إنشاء طلب Mercado Pago بإجمالي طلب WooCommerce كاملًا وإرساله إلى الجهاز الطرفي المحدد. تنتهي صلاحية طلب Mercado Pago بعد 5 دقائق.
تستطلع صفحة الدفع Mercado Pago كل 2 ثانية. ويمكن لخطاف الويب والفحص في الخلفية بعد 5 دقائق إتمام الطلب المدفوع أيضًا، حتى إذا أُغلق المتصفح. خطاف الويب اختياري لكنه موصى به؛ ومن دون Webhook secret، تظل الإشعارات تُعالَج، لكن لا يتم التحقق من توقيعها.
يجب أن يكون الجهاز الطرفي في PDV (الوضع المتكامل). تُشحن الأجهزة الطرفية في وضع STANDALONE، لذا بدّل إلى PDV في إعدادات بوابة الدفع وأعد تشغيل الجهاز قبل قبول المدفوعات.
الإعداد
تثبيت Mercado Pago Terminal for WooCommerce
نزّل ملف ZIP للإضافة (وليس ملف ZIP للشيفرة المصدرية من GitHub) من صفحة إصدارات GitHub. ارفعه عبر إضافات > إضافة جديد > رفع إضافة وفعّله بعد تثبيت WooCommerce وتفعيله.
إضافة بيانات اعتماد Mercado Pago
- انتقل إلى
WP Admin > WooCommerce > الإعدادات > المدفوعاتوافتح Mercado Pago Terminal - اختر Mode: يوجّه
Testإلى الجهاز الافتراضي التجريبي، بينما يوجّهLiveإلى الأجهزة الطرفية الحقيقية - الصق Access token (
APP_USR-…) الخاص بتطبيقك من Mercado Pago → Your integrations → Credentials
يرسل الرمز المميز TEST- في وضع Live المدفوعات إلى البيئة التجريبية. تحذّرك شاشة الإعدادات من هذا الجمع؛ الصق رمز الإنتاج قبل قبول مدفوعات حقيقية.
تسجيل خطاف الويب
- في Mercado Pago، انتقل إلى Your integrations → تطبيقك → Webhooks
- أضف عنوان URL لخطاف الويب الظاهر في شاشة إعدادات بوابة الدفع
- حدد حدث Order (Mercado Pago) واحفظ
- انسخ التوقيع السري إلى Webhook secret في WooCommerce
خطاف الويب اختياري. يكتمل الدفع بالاستطلاع من دونه، لكن ضبط السر يتيح للإضافة التحقق من توقيعات خطاف الويب.
إعداد أجهزتك الطرفية
- احفظ شاشة الإعدادات وأعد تحميلها. تعرض القائمة المنسدلة Default terminal وجدول Terminals الأجهزة الطرفية في حسابك
- إذا ظهر الجهاز الطرفي في وضع STANDALONE، فانقر Switch to PDV، ثم أعد تشغيل الجهاز الطرفي
- اختر Default terminal
- (اختياري) قيّد Enabled terminals بالأجهزة التي يمكن لأمناء الصندوق اختيارها. اتركه فارغًا للسماح بكل الأجهزة الطرفية؛ يظل الجهاز الافتراضي المحفوظ متاحًا حتى إن لم تحدده هنا
- (اختياري) فعّل Lock terminal selection لاستخدام الجهاز الافتراضي دائمًا ومنع أمناء الصندوق من تغييره. يتطلب ذلك تحديد جهاز افتراضي
- احفظ إعداداتك
التفعيل في WCPOS
- انتقل إلى
WP Admin > نقطة البيع > الإعدادات > إتمام الطلب - اعثر على بوابة الدفع Mercado Pago Terminal وفعّلها لنقطة البيع
- احفظ إعداداتك
يتحكم مربع الاختيار Enable/Disable في شاشة إعدادات WooCommerce بصفحة الدفع للمتجر الإلكتروني فقط. يستخدم WCPOS بوابة الدفع هذه بعد إعدادها، سواء تم تحديد هذا المربع أم لا.
مرجع الإعدادات
| الإعداد | وظيفته |
|---|---|
| Enable/Disable | يفعّل بوابة الدفع لإتمام الشراء في المتجر الإلكتروني. يُتحكم في تفعيل نقطة البيع ضمن نقطة البيع > الإعدادات > إتمام الطلب |
| Title | التسمية في صفحة الدفع؛ القيمة الافتراضية Mercado Pago Terminal |
| Description | وصف صفحة الدفع؛ القيمة الافتراضية Pay in person on a Mercado Pago Point terminal. |
| Mode | يستخدم Test (الافتراضي) الجهاز الافتراضي التجريبي؛ ويستخدم Live الأجهزة الطرفية الحقيقية مع بيانات اعتماد فعلية |
| Access token | رمز تطبيقك من Mercado Pago → Your integrations → Credentials. لا يُعرض الرمز المحفوظ مجددًا؛ اترك الحقل فارغًا للإبقاء عليه |
| Webhook secret | التوقيع السري من إعدادات خطاف الويب في Mercado Pago، ويُستخدم للتحقق من الإشعارات |
| Default terminal | الجهاز الطرفي المستخدم افتراضيًا عند الدفع، ويُجلب مباشرةً من حسابك. يظهر حقل نصي إذا تعذّر جلب القائمة |
| Enabled terminals | يقيّد الأجهزة الطرفية التي يمكن لأمناء الصندوق اختيارها. يسمح ترك الحقل فارغًا بكل الأجهزة؛ والجهاز الافتراضي متاح دائمًا. يُخفى إذا تعذّر تحميل القائمة |
| Lock terminal selection | يستخدم الجهاز الافتراضي دائمًا كي لا يتمكن أمناء الصندوق من تغييره. يتطلب تحديد جهاز افتراضي |
| Checkout debug logs | يعرض Show logs وCopy وClear في لوحة الدفع. يكون معطّلًا افتراضيًا؛ فعّله عند جمع السجلات للدعم |
| Log level | Off أو Errors only أو Debug. القيمة الافتراضية في هذا الإصدار هي Debug، ويسجل الطلبات والاستجابات بعد إزالة الأسرار |
أسفل الحقول، يعرض جدول Mercado Pago Terminal diagnostics فحص API (بما يشمل عدد الأجهزة الطرفية وعدد أجهزة PDV)، وآخر تحقق من خطاف الويب، والبيئة النشطة، وما إذا كانت بيانات الاعتماد مضبوطة، والجهاز الافتراضي، وعنوان URL لخطاف الويب، ورابط سجلات الدفع.
الاستخدام
معالجة المدفوعات
- Add Items: أضف المنتجات إلى سلة التسوق في نقطة البيع
- Select Gateway: اختر Mercado Pago Terminal كطريقة للدفع
- Choose Terminal: اختر جهازًا طرفيًا، أو استخدم الجهاز الافتراضي عند قفل الاختيار
- Start Payment: انقر Start Terminal Payment لإرسال إجمالي الطلب إلى الجهاز الطرفي
- Customer Payment: تابع رسائل الحالة —
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…— أثناء إتمام العميل للدفع على الجهاز الطرفي - Automatic Completion: عند تأكيد Mercado Pago للدفع، يكتمل الطلب وتنتقل نقطة البيع إلى الإيصال
عناصر التحكم بالدفع
- Start Terminal Payment: أرسل طلب دفع جديدًا إلى الجهاز الطرفي المحدد
- Cancel Terminal Payment: ألغِ الدفع فقط قبل أن يستلمه الجهاز الطرفي. بعد ذلك، ألغِه من الجهاز أو انتظر انتهاء الصلاحية بعد 5 دقائق
- إعادة تحميل الصفحة: تستأنف عملية دفع جارية
الإيصالات
لا يطبع الجهاز الطرفي إيصالًا. استخدم إيصال نقطة البيع بعد اكتمال الدفع.
المبالغ المستردة
افتح شاشة استرداد المبلغ لطلب WooCommerce واختر Refund via Mercado Pago Terminal لإرسال استرداد كامل أو جزئي. تتيح Mercado Pago استرداد المبالغ حتى 90 يومًا بعد الدفع.
لا تسمح بعض الجهات المستحوذة على البطاقات باسترداد المبالغ إلا من الجهاز الطرفي. في هذه الحالة، استرد المبلغ من الجهاز وسجّل استردادًا يدويًا في WooCommerce.
السجلات وحزمة الدعم
اعثر على السجلات ضمن WooCommerce > Status > السجلات، تحت المصدر mercadopago-terminal. مستوى السجل الافتراضي في هذا الإصدار هو Debug. تُسجّل الطلبات والاستجابات وخطافات الويب وتغييرات حالة الدفع مع حجب الأسرار وأرقام البطاقات.
انقر Download support bundle في شاشة إعدادات بوابة الدفع لتنزيل ملف .txt وإرفاقه بطلب الدعم. يتضمن تفاصيل البيئة، والإعدادات بعد إخفاء بيانات الاعتماد، وقائمة الأجهزة الطرفية وأوضاع تشغيلها، ومحاولات الدفع من أحدث 10 طلبات، وآخر 500 سطر من السجل؛ ولا يمكن استخدام أي مما فيه لقبول المدفوعات.
فعّل Checkout debug logs لإضافة Show logs وCopy وClear إلى لوحة الدفع. يُسجّل نشاط الدفع في سجلات WooCommerce بصرف النظر عن هذا الإعداد.
المتطلبات
النطاق والقيود
- يُحصّل الجهاز الطرفي إجمالي الطلب بالكامل. لا يُدعم دفع جزء من الطلب على الجهاز الطرفي
- الإكراميات غير مدعومة
- تُرسل المبالغ بمنزلتين عشريتين. ينبغي للمتاجر التي تبيع بالبيزو التشيلي أو الكولومبي إجراء دفعة اختبار أولًا للتأكد
- لا يُدعم الدفع عبر Blocks للمتجر الإلكتروني
- لم تعلن الإضافة بعد عن توافق HPOS
استكشاف الأخطاء وإصلاحها
المشكلات الشائعة
رفض Mercado Pago رمز الوصول (HTTP 401)
- رمز الوصول غير صالح أو قديم
- انسخ رمزًا جديدًا من Your integrations → Credentials واحفظه في Access token
لا تظهر أي أجهزة طرفية
- إذا لم تكن هناك أجهزة Point طرفية مرتبطة بالحساب، فسجّل الدخول على الجهاز الطرفي باستخدام حساب Mercado Pago هذا، وبدّل إلى PDV، ثم أعد تشغيله
- إذا ظهر Default terminal كحقل نصي بدلًا من قائمة منسدلة، فهذا يعني تعذّر جلب القائمة. تحقق من الرمز والتشخيصات، ثم أعد تحميل شاشة الإعدادات
الجهاز الطرفي في وضع STANDALONE
- تتطلب المدفوعات المتكاملة وضع PDV
- انقر Switch to PDV في جدول Terminals بشاشة الإعدادات، ثم أعد تشغيل الجهاز الطرفي
الدفع موجود بالفعل على الجهاز الطرفي
- استلم الجهاز الطرفي عملية الدفع، لذا لم يعد من الممكن إلغاؤها من WooCommerce
- ألغِ الدفع من الجهاز الطرفي أو انتظر انتهاء الصلاحية بعد 5 دقائق. تواصل صفحة الدفع التحقق من حالته
لم يسبق التحقق من خطاف الويب
- تحقق من عنوان URL لخطاف الويب والسر في Mercado Pago إذا أظهرت التشخيصات Last verified webhook: never
- إذا كان Webhook secret مفقودًا، فألصق التوقيع السري من Mercado Pago. يكتمل الدفع بالاستطلاع، لكن لا يُتحقق من توقيع الإشعارات في غياب السر
رفضت الجهة المستحوذة على البطاقة استرداد المبلغ
- لا تسمح بعض الجهات المستحوذة إلا باسترداد المبالغ من الجهاز الطرفي؛ كما تقيّد Mercado Pago الاسترداد بمدة 90 يومًا
- استرد المبلغ من الجهاز الطرفي وسجّل استردادًا يدويًا في WooCommerce
انتهت صلاحية الدفع على الجهاز الطرفي
- تنتهي صلاحية طلبات Mercado Pago بعد 5 دقائق
- ابدأ الدفع مجددًا
الحصول على المساعدة
- أرفق حزمة الدعم من شاشة إعدادات بوابة الدفع بطلب الدعم
- زُر مستودع GitHub للإبلاغ عن المشكلات
- تواصل مع دعم Mercado Pago للاستفسار عن الحساب والأجهزة