# قالب بوابة الدفع

يقدم لك قالب بوابة الدفع نقطة انطلاق لبناء بوابة دفع خاصة فقط بنظام نقاط البيع. ينتج مكون WordPress عملي مع ملف PHP واحد يمكنك تثبيته وتخصيصه ليناسب احتياجاتك.

## الميزات[​](#features "رابط مباشر إلى الميزات")

#### رمز بسيط

ملف PHP واحد يحتوي فقط على الأساسيات - سهل القراءة والتعديل

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

معطل على الخروج عبر الويب بشكل افتراضي، مفعل من خلال إعدادات WCPOS

#### إعداد تلقائي

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

#### إصدارات GitHub

ادفع زيادة في الإصدار ويقوم GitHub Actions ببناء ملف ZIP قابل للتنزيل

## البدء[​](#getting-started "رابط مباشر إلى البدء")

1

#### استنساخ مستودع القالب

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

cd woocommerce-gateway-template
```

أو انقر على زر **استخدم هذا القالب** في [مستودع GitHub](https://github.com/wcpos/woocommerce-gateway-template) لإنشاء نسخة خاصة بك.

2

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

```
./create-gateway.sh
```

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

3

#### تثبيت المكون

لديك خياران:

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

**الخيار ب - ضغط وتحميل** (أسهل لمعظم الأشخاص):

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

4

#### تفعيل في WCPOS

1. انتقل إلى **WP Admin > WCPOS > الإعدادات > الخروج**
2. ابحث عن بوابتك الجديدة في القائمة وقم بتفعيلها

ملاحظة

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

## الإعداد اليدوي[​](#manual-setup "رابط مباشر إلى الإعداد اليدوي")

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

| العنصر النائب                     | ما يجب إدخاله                             | مثال                            |
| --------------------------------- | ----------------------------------------- | ------------------------------- |
| `{{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` تلقائيًا من الاسم والشريحة، لذا تحتاج فقط إلى التفكير في هذه الأمور عند القيام بالإعداد اليدوي.

## كيف يعمل[​](#how-it-works "رابط مباشر إلى كيف يعمل")

يقوم المكون الذي تم إنشاؤه بتسجيل فئة بوابة دفع WooCommerce. إليك الأشياء الرئيسية التي تحتاج لمعرفتها:

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

## تخصيص بوابتك[​](#customising-your-gateway "رابط مباشر إلى تخصيص بوابتك")

### إضافة حقول الدفع[​](#adding-payment-fields "رابط مباشر إلى إضافة حقول الدفع")

إذا كانت بوابتك تحتاج إلى إدخال من أمين الصندوق (على سبيل المثال، رقم مرجعي)، قم بتجاوز طريقة `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()`.

### تغيير سلوك الدفع[​](#changing-payment-behaviour "رابط مباشر إلى تغيير سلوك الدفع")

يحدد القالب الافتراضي الطلبات كمدفوعة على الفور. إذا كانت سيرتك الذاتية تتطلب الدفع لاحقًا (مثل فاتورة)، استبدل `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 ),

    );

}
```

## إجراء التغييرات والتحديثات[​](#making-changes-and-updating "رابط مباشر إلى إجراء التغييرات والتحديثات")

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

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

نصيحة

سيسأل WordPress إذا كنت تريد استبدال المكون الحالي عند تحميل ملف zip بنفس اسم المكون - انقر على **استبدال الحالي بالملف المرفوع** للتحديث.

### إصدارات تلقائية مع GitHub[​](#automated-releases-with-github "رابط مباشر إلى إصدارات تلقائية مع GitHub")

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

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

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

## استكشاف الأخطاء وإصلاحها[​](#troubleshooting "رابط مباشر إلى استكشاف الأخطاء وإصلاحها")

البوابة لا تظهر في نظام نقاط البيع

* تحقق من أن المكون مفعل في **WP Admin > المكونات**
* انتقل إلى **WP Admin > WCPOS > الإعدادات > الخروج** وتأكد من تفعيل البوابة
* تحقق من أن WooCommerce مثبت ومفعل

البوابة تظهر على الخروج عبر الويب

* تأكد من تعيين `$this->enabled = 'no';` في مُنشئ البوابة
* تقوم WCPOS بتجاوز هذا الإعداد لطلبات نقاط البيع، لذلك يجب أن تظهر البوابة فقط في نقاط البيع

تبقى الطلبات في حالة 'المعالجة' بدلاً من 'الإنهاء'

* تقوم WooCommerce بتعيين حالة الطلب بناءً على أنواع المنتجات. تبقى الطلبات التي تحتوي على منتجات مادية في "المعالجة" - هذا سلوك عادي في WooCommerce. فقط الطلبات التي تحتوي على منتجات افتراضية أو قابلة للتنزيل يتم وضع علامة "مكتمل" تلقائيًا.

## الموارد[​](#resources "رابط مباشر إلى الموارد")

* **GitHub**: [woocommerce-gateway-template](https://github.com/wcpos/woocommerce-gateway-template)
* **API بوابة دفع WooCommerce**: [وثائق WC\_Payment\_Gateway](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html)

### بوابات أمثلة[​](#example-gateways "رابط مباشر إلى بوابات أمثلة")

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

* **[الفاتورة عبر البريد الإلكتروني](/ar/payment/gateways/email-invoice.md)** - ترسل بريدًا إلكترونيًا بالفاتورة حتى يتمكن العميل من الدفع لاحقًا
* **[الخروج عبر الويب](/ar/payment/gateways/web-checkout.md)** - يعيد التوجيه إلى متجر الويب للدفع