تجاوز إلى المحتوى الرئيسي
الإصدار: 1.x

نموذج بوابة الدفع

يمنحك نموذج بوابة الدفع نقطة انطلاق لإنشاء بوابة دفع خاصة بنقاط البيع. وينشئ إضافة WordPress جاهزة للعمل في ملف PHP واحد يمكنك تثبيته وتخصيصه لتلبية احتياجاتك.

الميزات​

رمز بسيط

ملف PHP واحد يتضمن الأساسيات فقط — سهل القراءة والتعديل

خاص بنقاط البيع

معطّل افتراضيًا في صفحة الدفع عبر الويب، ويُفعّل من خلال إعدادات WCPOS

إعداد تلقائي

يتولى برنامج نصي shell استبدال جميع العناصر النائبة نيابة عنك

إصدارات GitHub

ادفع تغيير رقم الإصدار، وستنشئ GitHub Actions ملف ZIP قابلًا للتنزيل

البدء​

1

استنساخ مستودع النموذج

git clone https://github.com/wcpos/woocommerce-gateway-template.git
cd woocommerce-gateway-template

أو انقر زر استخدم هذا القالب في مستودع GitHub لإنشاء نسخة خاصة بك.

2

تشغيل برنامج الإعداد

./create-gateway.sh

سيطلب البرنامج بعض التفاصيل — اسم بوابة الدفع ووصفًا موجزًا واسم مستخدم GitHub — ثم ينشئ إضافة جاهزة للاستخدام في الدليل الذي تختاره.

3

تثبيت الإضافة

لديك خياران:

الخيار أ — نسخ المجلد مباشرةً (إذا كان لديك وصول إلى الخادم): انسخ مجلد بوابة الدفع الذي تم إنشاؤه إلى دليل wp-content/plugins/ في موقعك.

الخيار ب — ضغط المجلد ورفعه (الأسهل لمعظم المستخدمين):

  1. اضغط المجلد الذي تم إنشاؤه في ملف .zip
  2. في WordPress، انتقل إلى الإضافات > أضف إضافة جديدة > رفع إضافة
  3. اختر ملف zip وانقر التثبيت الآن
4

تفعيلها في WCPOS

  1. انتقل إلى WP Admin > نقاط البيع > الإعدادات > الدفع
  2. ابحث عن بوابة الدفع الجديدة في القائمة وفعّلها
ملاحظة

تكون بوابة الدفع معطّلة افتراضيًا في صفحة الدفع العادية عبر الويب. ويتحكم WCPOS في بوابات الدفع التي تظهر في نقاط البيع من خلال إعداداته الخاصة.

الإعداد اليدوي​

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

العنصر النائبما يجب إدخالهمثال
{{GATEWAY_NAME}}الاسم المعروض لبوابة الدفعالدفع نقدًا
{{GATEWAY_SLUG}}معرّف آمن للاستخدام في URL (أحرف صغيرة وواصلات)cash-payment
{{GATEWAY_DESCRIPTION}}وصف موجز لبوابة الدفعقبول المدفوعات النقدية في WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}النص الذي يظهر لأمين الصندوق عند الدفعادفع نقدًا عند نقطة البيع
{{GITHUB_USERNAME}}اسم مستخدم GitHub الخاص بكkilbot
{{REPO_NAME}}اسم المستودع الخاص بكcash-payment-gateway
{{AUTHOR_NAME}}اسمكkilbot
{{GATEWAY_ID}}المعرّف المختصر مع شرطات سفلية بدلًا من الواصلاتcash_payment
{{GATEWAY_CLASS_NAME}}كتابة أول حرف من كل كلمة كبيرًا وربط الكلمات بشرطات سفليةCash_Payment
{{GATEWAY_FUNCTION_PREFIX}}مثل معرّف بوابة الدفعcash_payment

ثم أعد تسمية wcpos-{{GATEWAY_SLUG}}.php ليتطابق الاسم مع المعرّف المختصر الخاص بك (مثل wcpos-cash-payment.php).

نصيحة

يستخرج سكربت الإعداد تلقائيًا GATEWAY_ID وGATEWAY_CLASS_NAME وGATEWAY_FUNCTION_PREFIX من الاسم والمعرّف اللطيف (slug)، لذا لا تحتاج إلى التفكير فيها إلا عند إجراء الإعداد يدويًا.

آلية العمل​

تسجل الإضافة المُنشأة فئة بوابة دفع في WooCommerce. إليك أهم النقاط:

  • $this->enabled = 'no' — يخفي بوابة الدفع من صفحة الدفع عبر الويب. ويفعّلها WCPOS في نقاط البيع وفقًا لإعدادات نقاط البيع.
  • process_payment() — تستدعي $order->payment_complete()، ما يعلّم الطلب بأنه مدفوع ويتولى خفض المخزون تلقائيًا.
  • init_form_fields() — تحدد حقلي العنوان والوصف اللذين يظهران في إعدادات WooCommerce.

تخصيص بوابة الدفع​

إضافة حقول الدفع​

إذا كانت بوابة الدفع تحتاج إلى إدخال من أمين الصندوق (مثل رقم مرجعي)، فتجاوز الطريقة payment_fields():

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

يمكنك بعد ذلك قراءة القيمة المرسلة في process_payment() عبر $_POST['my_gateway_reference']. تذكّر تنقية أي إدخال باستخدام sanitize_text_field().

تغيير سلوك الدفع​

يعلّم النموذج الافتراضي الطلبات بأنها مدفوعة فورًا. إذا كان سير عملك يتطلب الدفع لاحقًا (مثل الفاتورة)، فاستبدل payment_complete() بتحديث للحالة:

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

إجراء التغييرات والتحديث​

بعد تثبيت بوابة الدفع، يمكنك مواصلة تعديل ملف الإضافة لضبط منطق الدفع. لتثبيت إصدار محدّث:

  1. عدّل wcpos-your-slug.php في المجلد الذي تم إنشاؤه
  2. حدّث رقم Version: في ترويسة الإضافة (مثلًا من 0.1.0 إلى 0.2.0)
  3. اضغط المجلد وارفعه مجددًا عبر الإضافات > أضف إضافة جديدة > رفع إضافة، أو استبدل المجلد مباشرةً في wp-content/plugins/
نصيحة

سيسألك WordPress عما إذا كنت تريد استبدال الإضافة الحالية عند رفع ملف zip بالاسم نفسه — انقر استبدال الحالية بالملف المرفوع للتحديث.

الإصدارات التلقائية باستخدام GitHub​

إذا دفعت بوابة الدفع إلى مستودع GitHub، فسيشمل النموذج سير عمل GitHub Actions ينشئ الإصدارات تلقائيًا:

  1. حدّث رقم Version: في ترويسة الإضافة
  2. أنشئ commit وادفعه إلى الفرع main
  3. ترصد GitHub Actions تغيير الإصدار وتنشئ إصدارًا جديدًا يتضمن ملف ZIP قابلًا للتنزيل

يمكن للمستخدمين الآخرين بعد ذلك تنزيل ملف ZIP من صفحة الإصدارات في مستودعك وتثبيته مثل أي إضافة WordPress.

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

بوابة الدفع لا تظهر في نقاط البيع
  • تحقق من تفعيل الإضافة ضمن WP Admin > الإضافات
  • انتقل إلى WP Admin > نقاط البيع > الإعدادات > الدفع وتأكد من تفعيل بوابة الدفع
  • تحقق من تثبيت WooCommerce وتفعيله
تظهر بوابة الدفع في صفحة الدفع عبر الويب
  • تأكد من تعيين $this->enabled = 'no'; في مُنشئ بوابة الدفع
  • يتجاوز WCPOS هذا الإعداد لطلبات نقاط البيع، لذا ينبغي ألا تظهر بوابة الدفع إلا في نقاط البيع
تبقى الطلبات بحالة 'قيد المعالجة' بدلًا من 'مكتمل'
  • يحدد WooCommerce حالة الطلب وفقًا لأنواع المنتجات. تبقى الطلبات التي تتضمن منتجات مادية بحالة "قيد المعالجة" — وهذا سلوك طبيعي في WooCommerce. أما الطلبات التي تحتوي على منتجات افتراضية أو قابلة للتنزيل فقط فتُعلّم تلقائيًا بأنها "مكتمل".

المتطلبات​

WCPOS: يتطلب الإصدار Pro لإتمام الدفع في نقاط البيع
WordPress: WordPress مع تثبيت WooCommerce
PHP: معرفة أساسية بـ PHP لتخصيص بوابة الدفع

المراجع​

بوابات أمثلة​

تلك البوابات الموجودة تم بناؤها بنفس النهج وهي مراجع جيدة: