تكامل المدفوعات الإلكترونية (Online Payments Integration)

وحدة المدفوعات الإلكترونية في Nama ERP تتيح لك قبول المدفوعات مباشرةً من عملائك عبر بوابات دفع آمنة. سواء كنت ترسل رابط دفع لفاتورة واحدة أو تُنشئ مئات روابط الدفع للأرصدة المستحقة، تُدير هذه الوحدة العملية كاملةً من إنشاء الرابط وحتى تأكيد الدفع وإنشاء سند القبض تلقائيًا.

فهم مسار الدفع (Understanding the Payment Flow)

عندما ينقر العميل على رابط الدفع، إليك ما يجري خلف الكواليس:

1. التحقق من الرابط (Link Validation) - يتحقق النظام من صلاحية الرابط (لم تنته مدته) ومن أن المستند لا يزال يستلزم الدفع
2. عرض صفحة الدفع (Payment Page Display) - يرى العميل صفحة دفع مخصصة تعرض المبلغ المستحق وتفاصيل المستند
3. إعادة التوجيه للبوابة (Gateway Redirect) - عند الاستعداد للدفع، يُعاد توجيه العميل إلى بوابة الدفع (KNet أو MyFatoorah)
4. معالجة الدفع (Payment Processing) - تعالج البوابة الدفع وتُعيد النتيجة
5. معالجة النجاح (Success Handling) - عند نجاح الدفع، يمكن لـ Nama تلقائيًا تشغيل مسارات كيان وإرسال إشعارات وإنشاء سندات قبض
6. صفحة التأكيد (Confirmation Page) - يرى العميل صفحة نجاح أو خطأ مع تفاصيل المعاملة

بوابات الدفع المدعومة (Supported Payment Gateways)

KNet (الكويت)

KNet هي شبكة الدفع الوطنية في الكويت. للتكامل مع KNet، ستحتاج إلى:

الحقل	الوصف
User Name	معرّف بوابة KNet الخاصة بك (tranportal ID)
Terminal Alias	الاسم المستعار المخصص لطرفيتك من KNet
GUI URL	العنوان العام لخادمك الذي ستُستقبل عليه استجابات الدفع
URL Prefix Identifier	معرّف فريد لروابط الدفع الخاصة بك (مثل "mycompany")
Resource Files Path	مسار الخادم الذي يحتوي على ملفي resource.cgn وkeystore.bin من KNet

هام

يتطلب KNet وجود ملفَّي شهادة (resource.cgn وkeystore.bin) يجب وضعهما على خادمك. يتم توفير هذين الملفين من KNet أثناء تسجيل التاجر وتحتوي على مفاتيح التشفير الخاصة بك.

MyFatoorah

MyFatoorah بوابة دفع شائعة في منطقة الشرق الأوسط تدعم طرق دفع متعددة منها البطاقات وApple Pay وخيارات الدفع المحلية.

الحقل	الوصف
API Token	رمز API الخاص بك في MyFatoorah من لوحة تحكم التاجر
GUI URL	العنوان العام لخادمك لاستقبال استجابات الدفع

MyFatoorah أسهل في الإعداد إذ تستخدم المصادقة عبر API بدلًا من ملفات الشهادات.

إعداد تكوين المدفوعات الإلكترونية (Setting Up Online Payment Configuration)

انتقل إلى Basic > Documents > Online Payment Configuration لإنشاء إعدادات بوابة الدفع.

الإعداد الأساسي (Basic Setup)

1. أنشئ تكوينًا جديدًا وأعطه رمزًا دالًا (مثل "KNET-MAIN" أو "MYFATOORAH-PROD")
2. اختر النوع (Type) - اختر إما KNet أو MyFatoorah
3. أدخل بيانات اعتماد البوابة بحسب مزودك (راجع الحقول أعلاه)
4. حدد GUI URL - وهو عنوان خادمك العام، مثل https://yourcompany.com/erp/

إعدادات انتهاء صلاحية الروابط (Link Expiration Settings)

روابط الدفع لا تبقى صالحة إلى الأبد. يمكنك التحكم في مدة صلاحيتها:

• Expire Link After (Hours) - عدد الساعات قبل انتهاء صلاحية الرابط. إذا تُرك فارغًا، تنتهي صلاحية الروابط بعد سنة.

النظام ذكي في حساب الانتهاء - يمكنه تجاهل عطل نهاية الأسبوع والإجازات عند الحساب. اضبط ذلك باستخدام:

• Weekend Days - حدد أي الأيام هي إجازات الأسبوع (الجمعة/السبت لدول الخليج، السبت/الأحد في مناطق أخرى)
• Holidays Collection - أضف تواريخ محددة يجب استبعادها من حسابات الانتهاء

على سبيل المثال، إذا ضبطت "انتهاء الصلاحية بعد 24 ساعة" والجمعة/السبت إجازة أسبوعية، فإن رابطًا أُنشئ الخميس الساعة 10 صباحًا لن تنتهي صلاحيته إلا الأحد الساعة 10 صباحًا (متجاوزًا الجمعة والسبت).

قوالب الدفع (Payment Templates)

تتحكم القوالب فيما يراه عملاؤك في كل مرحلة من مراحل الدفع. يدعم كل قالب عناصر نائبة ديناميكية تُستبدل بقيم المستند الفعلية.

القالب	متى يُعرض
Payment Template	صفحة الدفع الأولية التي تعرض تفاصيل الفاتورة وزر "Pay Now"
Success Template	يُعرض بعد نجاح الدفع
Error Template	يُعرض عند فشل الدفع أو رفضه
Bad Transaction Template	يُعرض عند عدم الموافقة على المعاملة
Expired Link Template	يُعرض عند النقر على رابط منتهي الصلاحية
Totally Paid Template	يُعرض عند سداد الفاتورة بالكامل مسبقًا
Not Found Template	يُعرض عند عدم وجود المستند
Type Not Supported Template	يُعرض عندما لا يدعم نوع المستند المدفوعات الإلكترونية

تحميل القوالب الافتراضية

انقر على زر "Calculate Default Templates" لتحميل قوالب HTML الافتراضية للنظام. يمكنك بعد ذلك تخصيصها لتتناسب مع هوية علامتك التجارية.

استخدام العناصر النائبة في القوالب (Using Placeholders in Templates)

تدعم القوالب محرك قوالب Nama. يمكنك تضمين حقول المستند باستخدام الأقواس المعقوفة:

<h2>Invoice #{code}</h2>
<p>Amount Due: {currency.code} {netTotal}</p>
<p>Customer: {customer.name1}</p>

بعد الدفع، يمكنك أيضًا الوصول إلى استجابة الدفع:

<p>Transaction ID: {opResponse.transId}</p>
<p>Authorization: {opResponse.auth}</p>
<p>Amount Paid: {opResponse.amt}</p>
<p>Date: {opResponse.date}</p>

مرجع خريطة استجابة الدفع ($map.opResponse)

كائن opResponse متاح في القوالب (عبر {$map.opResponse.fieldName}) وفي مسارات الكيان (عبر x=$map.opResponse.fieldName). الحقول المتاحة تختلف باختلاف بوابة الدفع:

حقول استجابة KNet (انقر للتوسيع)

{
  // Core Transaction Data
  "result": "CAPTURED",           // Transaction result (CAPTURED, NOT CAPTURED, etc.)
  "amt": "150.000",               // Transaction amount
  "auth": "123456",               // Authorization code from bank
  "ref": "789012345678",          // Reference number
  "transId": "1234567890123456",  // Transaction ID
  "paymentId": "12345678901234",  // Payment ID
  "trackId": "9876543210",        // Your tracking ID
  "date": "01/15/2025 14:30:00",  // Transaction date/time

  // Card Information
  "card": "************1234",     // Masked card number
  "type": "VISA",                 // Card type (VISA, MASTERCARD, etc.)
  "member": "CARDHOLDER NAME",    // Cardholder name
  "expMonth": "12",               // Card expiry month
  "expYear": "2027",              // Card expiry year

  // Currency & Amount
  "currency": "414",              // Currency code (414 = KWD)
  "convertedCrncyCD": "",         // Converted currency code (if applicable)

  // User Defined Fields
  "udf1": "",                     // Custom field 1
  "udf2": "",                     // Custom field 2
  "udf3": "",                     // Custom field 3
  "udf4": "",                     // Custom field 4
  "udf5": "",                     // Custom field 5
  "custid": "",                   // Customer ID

  // 3D Secure / Authentication
  "eci": "",                      // Electronic Commerce Indicator
  "cavv": "",                     // Cardholder Authentication Verification Value
  "xid": "",                      // 3D Secure transaction ID
  "authStatus": "",               // Authentication status
  "enrolmntStatus": "",           // 3D Secure enrollment status

  // Error Information
  "error": "",                    // Error code
  "error_text": "",               // Error description
  "errorMessage": "",             // Combined error message (on failure)

  // Response Codes
  "responseCode": "",             // Gateway response code
  "avr": "",                      // Address verification result
  "cvv2Verification": "",         // CVV2 verification result

  // Additional Technical Fields
  "action": "1",                  // Action type (1 = Purchase)
  "language": "en",               // Language code
  "responseURL": "",              // Callback URL
  "errorURL": "",                 // Error callback URL
  "alias": "",                    // Terminal alias
  "tranportalId": "",             // Tranportal ID
  "rawResponse": ""               // Raw response from gateway
}

حقول استجابة MyFatoorah (انقر للتوسيع)

{
  // Core Transaction Data (Success)
  "amt": "150.000",               // Paid amount
  "date": "15/01/2025",           // Transaction date
  "paymentId": "07012345678901",  // MyFatoorah payment ID
  "transId": "1234567890123456",  // Transaction ID
  "ref": "REF123456",             // Reference ID
  "auth": "AUTH123",              // Authorization ID

  // Error Information (Failure)
  "errorMessage": "MF002: Bank declined" // Error message with code
}

رموز أخطاء MyFatoorah في errorMessage:

• MF001 - فشل مصادقة 3DS
• MF002 - رفض البنك (رصيد غير كافٍ، بطاقة غير صالحة)
• MF003 - حجب بوابة الدفع (كشف الاحتيال)
• MF004 - رصيد غير كافٍ
• MF005 - انتهت مهلة الجلسة
• MF006 - إلغاء المعاملة
• MF007 - انتهت صلاحية البطاقة
• MF008 - جهة إصدار البطاقة لا تستجيب
• MF009 - رفض من إدارة المخاطر
• MF010 - رمز CVV غير صحيح
• MF020 - فشل غير محدد

الاستخدام في مسارات الكيان (Using in Entity Flows)

عند ضبط مسارات الكيان التي تعمل بعد الدفع (Success Entity Flow أو Error Entity Flow)، يمكنك الوصول إلى هذه القيم باستخدام المتغير $map:

// In entity flow parameter expressions:
x=$map.opResponse.auth           // Get authorization code
x=$map.opResponse.amt            // Get paid amount
x=$map.opResponse.transId        // Get transaction ID
x=$map.opResponse.errorMessage   // Get error message (on failure)

إجراءات الدفع - أتمتة سير العمل بعد الدفع (Payment Actions - Automating Post-Payment Workflows)

هنا تكمن القوة الحقيقية. عند نجاح الدفع (أو فشله)، يمكنك تشغيل إجراءات تلقائية في النظام.

الحقل	الغرض
Success Entity Flow	مسار كيان يعمل بعد نجاح الدفع (مثل تعليم الفاتورة مدفوعة، تغيير الحالة)
Success Notification	إرسال إشعار بريد إلكتروني/رسالة نصية بعد نجاح الدفع
Error Entity Flow	تشغيل هذا المسار عند فشل الدفع
Payment Method	إضافة سطر دفع للمستند تلقائيًا باستخدام هذه الطريقة

Payment Method مفيد بشكل خاص - عند تعيينه، يضيف النظام تلقائيًا دفعة على الفاتورة عند نجاح الدفع الإلكتروني، مما قد يُشغّل إنشاء سند القبض إذا تم تكوينه.

إجراءات الدفع الشرطية (Conditional Payment Actions)

أحيانًا تحتاج إلى سلوكيات مختلفة بحسب نوع المستند أو شروط معينة. مجموعة Details تتيح إنشاء قواعد شرطية:

الحقل	الغرض
For Type	تطبيق هذه القاعدة فقط على نوع مستند محدد (مثل فاتورة مبيعات، أمر مبيعات)
Entity Type List	أو تطبيقها على أنواع مستندات متعددة من قائمة محددة مسبقًا
Apply When Query	شرط استعلام يجب أن يكون صحيحًا لتطبيق هذه القاعدة
Do Not Apply When Query	تجاهل هذه القاعدة عند تحقق هذا الشرط

كل سطر تفاصيل له قسم Payment Actions الخاص، بحيث يمكنك وضع مسارات نجاح مختلفة وإشعارات وقوالب لسيناريوهات مختلفة.

مثال: قد ترغب في:

• فواتير المبيعات تُشغّل مسار "Mark as Paid" وترسل بريدًا إلكترونيًا
• أوامر المبيعات تُشغّل مسار "Confirm Order" وترسل بريدًا إلكترونيًا مختلفًا
• الفواتير ذات القيمة العالية (أكثر من 1000) ترسل إشعارًا إضافيًا لمدير المبيعات

تعيين الحقول (Fields Mapping - KNet)

لتكامل KNet، يمكنك تمرير بيانات إضافية إلى بوابة الدفع باستخدام حقول User Defined Fields (UDF1-UDF5) ومعرّف العميل:

نوع الحقل	الوصف
UDF1 - UDF5	حقول مخصصة تظهر في تقارير التسوية الخاصة بك في KNet
CustomerId	معرّف العميل للمعاملة

عمود Value Template يدعم العناصر النائبة، بحيث يمكنك تعبئة هذه الحقول ديناميكيًا:

{customer.code}
{code}
{netTotal}

إعداد مصدر الفرع (Subsidiary Source Configuration)

عند استخدام Payment Links Creation Document لإنشاء الروابط بالجملة، تحتاج إلى إخبار النظام بالحقل الذي يحتوي على العميل/الفرع لكل نوع مستند:

الحقل	الغرض
Entity Type	نوع المستند (مثل SalesInvoice)
Field ID	الحقل الذي يحتوي على مرجع الفرع (مثل customer)

يُستخدم هذا التعيين عند تجميع الفواتير حسب العميل لإنشاء روابط الدفع بالجملة.

إنشاء روابط الدفع (Generating Payment Links)

هناك طريقتان لإنشاء روابط الدفع:

الطريقة الأولى: إنشاء الرابط المباشر (Method 1: Direct Link Generation)

للمستندات التي تدعم المدفوعات الإلكترونية (مثل فواتير المبيعات)، يمكنك إنشاء رابط دفع مباشرةً. يُنشئ النظام عنوان URL مشفرًا يحتوي على:

• معرّف تكوين الدفع
• نوع المستند ومعرّفه
• طابع وقت الانتهاء

صيغة URL تبدو مثل: https://yourserver.com/erp/op/prefix/ENCRYPTED_DATA

إنشاء الروابط تلقائيًا عبر مسارات الكيان

يمكنك إنشاء روابط دفع KNet تلقائيًا باستخدام مسار الكيان EAGenerateKNetPaymentURLs. هذا مفيد عندما تريد إنشاء روابط الدفع كجزء من سير عمل آلي (مثل عند اعتماد فاتورة). يُنشئ المسار عناوين URL مباشرة للبوابة وعناوين إعادة توجيه، ويخزنها في حقول المستند المحددة. راجع توثيق EAGenerateKNetPaymentURLs للاطلاع على المعاملات وتفاصيل الإعداد.

الطريقة الثانية: روابط الدفع بالجملة (Method 2: Bulk Payment Links)

انتقل إلى Basic > Documents > Payment Links Creation Document للإنشاء بالجملة.

تتيح هذه الأداة القوية:

1. تصفية المستندات حسب النوع والنطاق الزمني والدفتر والتوجيه أو الفترة
2. إيجاد الفواتير التي تستحق أقساطها خلال عدد محدد من الأيام
3. تجميع المبالغ حسب العميل
4. إنشاء روابط الدفع لجميع العملاء المحددين مرة واحدة

استخدام مستند إنشاء روابط الدفع (Using the Payment Links Creation Document)

1. اختر نوع المستند (Select Document Type) - اختر فاتورة مبيعات أو أمر مبيعات أو فاتورة مشتريات متنوعة
2. حدد المعايير (Set Filters) - حدد نطاقات التواريخ والدفاتر والتوجيهات أو الفترات لتضييق نطاق المستندات
3. فلتر الأيام المتبقية (Remaining Days Filter) - ابحث عن الأقساط المستحقة خلال X من الأيام
4. انقر "Collect Docs" - يبحث النظام عن المستندات المطابقة ويجمعها حسب العميل
5. راجع التفاصيل (Review the Details) - اطلع على الفواتير/الأقساط الفردية في تبويب التفاصيل
6. راجع سطور الروابط (Review Link Lines) - اطلع على المبالغ المجمعة لكل عميل مع بيانات التواصل
7. احفظ وأنشئ الروابط (Save and Create Links) - انقر "Create Payment Links" لإنشاء روابط لجميع العملاء

يقوم النظام تلقائيًا بـ:

• تجميع الفواتير حسب العميل
• سحب بيانات تواصل العميل (البريد الإلكتروني، الجوال)
• إنشاء روابط دفع فردية لكل عميل
• تخزين الروابط للرجوع إليها لاحقًا

حقول سطور الروابط (Link Lines Fields)

الحقل	الوصف
Subsidiary	العميل/المورد
Customer Name	يُملأ تلقائيًا من الفرع
Customer Email	البريد الإلكتروني لتسليم رابط الدفع
Mobile Country Code	رمز الدولة لتسليم الرسائل النصية
Mobile Number	رقم الهاتف لتسليم الرسائل النصية
Value	إجمالي المبلغ المطلوب تحصيله
Payment Link	الرابط المُنشأ (بعد النقر على "Create Payment Links")
Invoice ID	معرّف فاتورة MyFatoorah (للتتبع)

خيارات الإشعارات (MyFatoorah) (Notification Options)

يمكن لـ MyFatoorah إرسال رابط الدفع تلقائيًا للعملاء:

• LNK - إنشاء الرابط فقط (بدون إرسال تلقائي)
• EML - الإرسال عبر البريد الإلكتروني
• SMS - الإرسال عبر الرسائل النصية
• ALL - الإرسال عبر البريد الإلكتروني والرسائل النصية معًا

يختار النظام تلقائيًا الخيار المناسب بناءً على حقول التواصل التي تقدمها.

تتبع المعاملات (Transaction Tracking)

كل محاولة دفع تُسجَّل في Online Payment Transaction System Entry. يتتبع هذا السجل:

الحقل	الوصف
Document	الفاتورة/الأمر المدفوع
Online Payment Config	تكوين الدفع المستخدم
Track ID / Invoice ID	معرّف معاملة البوابة
Transaction Status	الحالة الحالية (Initial, Captured, Paid, إلخ)
Paid Amount	المبلغ المدفوع
Authorization Number	رمز ترخيص البنك
Transaction ID	معرّف معاملة البوابة
Reference	مرجع إضافي من البوابة
Link Status	هل الرابط صالح أم مدفوع أم منتهي الصلاحية

إنشاء سند القبض تلقائيًا (Automatic Receipt Voucher Creation)

عند الضبط عبر إعدادات توجيه المستند، يمكن للنظام إنشاء سندات قبض تلقائيًا عند نجاح الدفع. هذا مفيد بشكل خاص لسير عمل Payment Links Creation Document حيث تجمع مدفوعات لفواتير متعددة.

إنشاء سند القبض يراعي تكوين المحاسبة ويمكنه:

• إنشاء سند واحد لكل دفعة
• تطبيق الدفعة على حساب العميل الصحيح
• الربط بالفواتير الأصلية

اعتبارات الأمان (Security Considerations)

• تستخدم روابط الدفع تشفيرًا قويًا لحماية معرّفات المستندات والتكوينات
• تنتهي صلاحية الروابط تلقائيًا بناءً على تكوينك
• يتحقق النظام من وجود المستندات وأنها لا تزال تستلزم الدفع قبل المعالجة
• تُسجَّل جميع محاولات الدفع لأغراض التدقيق
• يجب الحفاظ على سرية رموز API وبيانات الاعتماد وعدم مشاركتها

سيناريوهات شائعة (Common Scenarios)

السيناريو الأول: دفع فاتورة بسيطة (Scenario 1: Simple Invoice Payment)

1. أنشئ Online Payment Configuration لبوابتك
2. أعدّ القوالب الافتراضية واختياريًا مسار كيان للنجاح
3. أنشئ روابط الدفع من فواتيرك
4. شارك الروابط مع العملاء عبر البريد الإلكتروني أو المراسلة
5. يدفع العملاء ويتولى النظام الباقي

السيناريو الثاني: تحصيل كشف حساب شهري (Scenario 2: Monthly Statement Collection)

1. أنشئ Payment Links Creation Document
2. فلتر الفواتير غير المدفوعة من الشهر السابق
3. أنشئ روابط لجميع العملاء ذوي الأرصدة المستحقة
4. يرسل MyFatoorah تلقائيًا روابط الدفع عبر البريد الإلكتروني/الرسائل النصية
5. تتبع المدفوعات عند ورودها

السيناريو الثالث: قواعد مختلفة لأنواع مستندات مختلفة (Scenario 3: Different Rules for Different Document Types)

1. في Online Payment Configuration، أضف سطور تفاصيل
2. حدد قواعد مختلفة لفواتير المبيعات مقابل أوامر المبيعات
3. اضبط مسارات نجاح وإشعارات مختلفة لكل منها
4. يطبّق النظام تلقائيًا القواعد الصحيحة بناءً على نوع المستند

رموز الأخطاء (MyFatoorah) (Error Codes)

عند فشل المدفوعات، يوفر MyFatoorah رموز أخطاء محددة:

الرمز	المعنى
MF001	فشل مصادقة 3DS (كلمة مرور خاطئة، غير مسجّل، أو مشكلة في جهة الإصدار)
MF002	رفض البنك (بطاقة غير صالحة، رصيد غير كافٍ، بطاقة منتهية)
MF003	حجب البوابة (بطاقة غير مدعومة، كشف الاحتيال، قواعد الأمان)
MF004	رصيد غير كافٍ
MF005	انتهت مهلة الجلسة
MF006	إلغاء المعاملة من المستخدم
MF007	البطاقة منتهية الصلاحية
MF008	جهة إصدار البطاقة لا تستجيب
MF009	رفض من إدارة المخاطر
MF010	رمز الأمان (CVV) غير صحيح
MF020	فشل غير محدد

تساعد رموز الأخطاء هذه أنت وعملاءك على فهم سبب فشل الدفع والإجراء التصحيحي المطلوب.