إذا كنت تعمل على تطبيق أندرويد يحتاج إلى تنفيذ عمليات دفع عبر أجهزة نقاط البيع، فإن ربط Hala POS داخل مشروعك يسمح للتطبيق بإرسال طلبات الدفع أو الاسترجاع إلى تطبيق الدفع، ثم استقبال نتيجة العملية ومعالجتها داخل التطبيق.

بحسب ملف التكامل الرسمي المرفق، يتم الربط من خلال إضافة ملف integrationSDK.arr إلى مشروع Android، ثم تهيئة الـ SDK داخل الـ Activity، وبعدها استخدام دوال جاهزة لإنشاء طلبات الدفع وقراءة الاستجابة. :contentReference[oaicite:0]{index=0}

Hala POS Payment Integration هو SDK مخصص لربط تطبيقك مع تطبيق الدفع الخاص بـ Hala. الفكرة الأساسية أن تطبيقك يقوم بإنشاء طلب دفع أو استرجاع، ثم يقوم محرك التكامل بتمرير الطلب إلى تطبيق الدفع، وبعد تنفيذ العملية يتم إرجاع النتيجة إلى تطبيقك.

سير العملية كما هو موضح في ملف الربط يكون بالشكل التالي:

1. يقوم التطبيق المدمج بإرسال الطلب.
2. يقوم Integration Engine بالاستماع للطلب القادم.
3. يتم التحقق من صحة البيانات.
4. يتم تمرير البيانات إلى تطبيق الدفع.
5. تتم معالجة عملية الدفع.
6. يتم إرجاع النتيجة إلى محرك التكامل.
7. يتم إرسال نتيجة العملية إلى التطبيق المدمج.

قبل البدء، تأكد من توفر ملف SDK الخاص بالتكامل:

integrationSDK.arr

هذا الملف يجب إضافته داخل مجلد libs في مشروع Android الخاص بك.

افتح مشروعك في Android Studio، ثم أضف ملف:

integrationSDK.arr

داخل المسار التالي:

app/libs/

إذا لم يكن مجلد libs موجودًا، يمكنك إنشاؤه يدويًا داخل مجلد app.

بعد إضافة الملف داخل مجلد libs، افتح ملف build.gradle الخاص بالموديول، ثم أضف الاعتماد التالي داخل قسم dependencies:

dependencies {
...
    implementation files('../libs/AppToApp-v2.1.1.aar')
    implementation files('../libs/T1_USDK_1223.jar')
}

بعد ذلك قم بعمل Sync للمشروع من Android Studio حتى يتعرف المشروع على ملف SDK.

في حال كان التطبيق يعمل على Android API Level 30 أو أعلى، يجب إضافة وسم queries داخل ملف AndroidManifest.xml قبل وسم application.

<queries>
    <package android:name="com.example.halalah" />
</queries>

مثال كامل:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <queries>
        <package android:name="com.example.halalah" />
    </queries>

    <application
        android:theme="@style/AppTheme"
        android:label="@string/app_name">

    </application>

</manifest>

بعد إضافة SDK للمشروع، يجب إنشاء instance من IntegrationPOSSDK داخل الـ Activity، ثم تهيئته داخل دالة onCreate.

var integrationSDK = IntegrationPOSSDK.getInstance()

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    integrationSDK!!.initializeSDK(
        this, // ViewModelStoreOwner
        this  // Activity
    )
}

بهذه الخطوة يصبح SDK جاهزًا للتعامل مع طلبات الدفع والاسترجاع.

لإنشاء عملية دفع عادية، استخدم الدالة createRequest مع تمرير نوع العملية والمبلغ المطلوب.

fun createRequest(
    transactionType: TransactionType,
    requestAmount: String
): Int

مثال:

val requestId = integrationSDK?.createRequest(
    TransactionType.PURCHASE,
    "40.00"
)

القيمة الراجعة من الدالة هي requestId، وهو رقم العملية الذي يمكن استخدامه لاحقًا لجلب نتيجة العملية.

لإنشاء عملية استرجاع، تحتاج إلى تمرير بيانات إضافية مثل كلمة مرور الاسترجاع، رقم RRN، تاريخ العملية، ورمز الموافقة.

fun createRequest(
    transactionType: TransactionType,
    requestAmount: String,
    PWD: String,
    RRN: String,
    transactionDate: String,
    transactionApprovalCode: String
): Int

مثال:

val requestId = integrationSDK?.createRequest(
    TransactionType.REFUND,
    "40.00",
    PWD = "123456",
    RRN = "123456789012",
    transactionDate = "1/2021",
    transactionApprovalCode = "871237"
)

بعد إنشاء الطلب، يمكنك استخدام رقم الطلب requestId لجلب نتيجة العملية.

fun getResponseByID(requestID: Int?): PaymentResponse?

مثال:

val integrationResponse = integrationSDK?.getResponseByID(requestId)

هذه الدالة مفيدة عندما تريد قراءة نتيجة عملية معينة بناءً على رقم الطلب.

يمكنك أيضًا قراءة آخر نتيجة عملية تم تنفيذها من خلال الدالة:

fun getLastResponse(): IntegrationResponse?

مثال:

val integrationResponse = integrationSDK?.getLastResponse()

تحتوي الاستجابة على معلومات مهمة تساعدك في معرفة حالة العملية وتفاصيل الدفع.

من أهم الحقول التي يجب التعامل معها داخل التطبيق حقل transactionStatus، حيث يوضح نتيجة العملية.

قد تحتوي نتيجة العملية على بيانات مثل:

إذا أردت حذف طلب معين، يمكنك استخدام الدالة:

fun deleteRequestByID(requestID: String)

مثال:

integrationSDK?.deleteRequestByID("2153")

لمسح جميع الاستجابات المخزنة، استخدم:

fun clearResponse()

مثال:

integrationSDK?.clearResponse()

class PaymentActivity : AppCompatActivity() {

    private var integrationSDK = IntegrationPOSSDK.getInstance()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        integrationSDK!!.initializeSDK(
            this,
            this
        )

        startPurchase()
    }

    private fun startPurchase() {
        val requestId = integrationSDK?.createRequest(
            TransactionType.PURCHASE,
            "40.00"
        )

        if (requestId != null && requestId != -1) {
            val response = integrationSDK?.getResponseByID(requestId)

            if (response != null) {
                // تعامل مع نتيجة الدفع هنا
            }
        } else {
            // البيانات غير صحيحة أو فشل إنشاء الطلب
        }
    }
}

ربط Hala POS داخل مشروع أندرويد يتم عبر خطوات واضحة: إضافة ملف SDK إلى مجلد libs، تعريفه داخل Gradle، إضافة إعدادات AndroidManifest.xml، ثم تهيئة IntegrationPOSSDK داخل الـ Activity. بعد ذلك يمكنك إنشاء عمليات شراء أو استرجاع، وقراءة نتائج العمليات من خلال requestId أو من خلال آخر استجابة محفوظة.

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