شرح بوابة الدفع Paymob في فلاتر (Paymob In Flutter)

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

في هذا المقال، سنقدم لكم شرحًا مفصلاً لطريقة الدفع Paymob واستخدام بطاقات الفيزا ومحافظ الكاش الإلكترونية مثل فودافون كاش. سنستعرض الخطوات الأساسية التي يجب اتباعها لتكوين واجهة برمجة التطبيقات (API) للدفع المقدمة من Paymob، بما في ذلك إعداد الطلب، وتحويل الدفع، وإعادة التوجيه إلى صفحة الدفع.

انشاء الحساب Paymob:

إن التسجيل للحصول على حساب هو الخطوة الأولى للاستفادة من خدمات Accept التي تقدمها بوابة الدفع Paymob. لإنشاء حسابك، يرجى اتباع الخطوات التالية:

1. انتقل إلى صفحة الصفحة الرئيسية لـ Accept وانقر على “إنشاء حساب”.
2. ستتم إعادة توجيهك إلى صفحة التسجيل. يرجى ملء النموذج بالمعلومات المطلوبة وتحديد خانة “لست روبوتًا” ثم انقر على “التسجيل”.
3. بعد ذلك، ستتلقى رسالة تأكيد على البريد الإلكتروني الذي قمت بالتسجيل به. يرجى التحقق من صندوق الوارد الخاص بك والنقر على Start Accepting “بدء القبول”.
4. ممتاز! لقد أنشأت حساب Accept الجديد الخاص بك. يمكنك الآن الانتقال إلى صفحة تسجيل الدخول والبدء في قبول المدفوعات عبر الإنترنت من عملائك.

ملاحظة: سيتم وضع حالة الحساب الذي تم إنشاؤه على أنه Test “اختبار”، وهذا سيسمح لك باختبار جميع خدمات Accept. عند الانتهاء من مرحلة الاختبار، يرجى إرسال طلب إلى “support@paymob.com” لتغيير حالة الحساب إلى “Live“.

بعد إنشاء حسابك وتفعيله، يمكنك الوصول إلى لوحة التحكم الخاصة بـ Accept والبدء في استخدام خدماتها المتنوعة لتسهيل عمليات الدفع عبر الإنترنت.

“اقرأ أيضاً: شرح استخدام path_provider في Flutter“

خطوات الاعداد لطرق الدفع:

الخطوة 1: طلب رمز المصادقة token

أول خطوة يجب القيام بها هي طلب المصادقة قبل التعامل مع أي من خدمات Accept’s APIs الأخرى المقدمة من Paymob. يتم إرسال طلب المصادقة الى “https://accept.paymob.com/api/auth/tokens” كطلب POST ويحتوي على كائن JSON يحتوي على api_key الخاص بك الموجود في لوحة التحكم الخاصة بك.

سيتم ارساله هكذا:

{
    "api_key": "ZXlKaGJHY2lPaUpJVXpVe..."
}

بعد إرسال الطلب، ستتلقى استجابة تحتوي على رمز المصادقة token الذي سيكون صالحًا لمدة ساعة واحدة من وقت الإنشاء.

{
    "token": "ZXlKaGJHY2lPaUpJVXpVeE1pSXNJ..."
}

ستحتاج إلى استخدام رمز المصادقة token هذا في الخطوات القادمة.

“اقرأ أيضاً: شرح استخدام Image Picker في Flutter“

الخطوة 2: تسجيل الطلب والحصول على Order ID

في هذه الخطوة، ستقوم بتسجيل طلب في قاعدة بيانات بوابة الدفع Paymob، حتى تتمكن من الدفع لاحقًا باستخدام عملية تحويل. سيكون لديك معرّف الطلب Order ID الذي ستستخدمه لربط العمليات المنفذة بنظامك، حيث يمكن أن يحتوي طلب واحد على أكثر من عملية تحويل.

يتم إرسال طلب التسجيل الى “https://accept.paymob.com/api/ecommerce/orders” كطلب POST ويحتوي على كائن JSON يحتوي على المعلومات المطلوبة لتسجيل الطلب، مثل رمز المصادقة token الذي حصلنا عليه في العملية السابقة والمبلغ ومعرّف الطلب ومعلومات الشحن وغيرها.

{
  "auth_token": "ZXlKaGlPaUpJVXpVeE1pSX1Y0NJmV5Sn...",
  "delivery_needed": "false",
  "amount_cents": "100",
  "currency": "EGP",
  "merchant_order_id": 5,
  "items": [
    {
        "name": "ASC1515",
        "amount_cents": "500000",
        "description": "ساعة ذكية",
        "quantity": "1"
    },
    { 
        "name": "ERT6565",
        "amount_cents": "200000",
        "description": "باور بانك",
        "quantity": "1"
    }
  ],
  "shipping_data": {
    "apartment": "803", 
    "email": "example@example.com", 
    "floor": "42", 
    "first_name": "Clifford", 
    "street": "Ethan Land", 
    "building": "8028", 
    "phone_number": "+86(8)9135210487", 
    "postal_code": "01898",
    "extra_description": "8 جيجابايت رام، 128 جيجابايت",
    "city": "Jaskolskiburgh", 
    "country": "CR", 
    "last_name": "Nicolas", 
    "state": "Utah"
  },
  "shipping_details": {
    "notes" : "اختبار",
    "number_of_packages": 1,
    "weight" : 1,
    "weight_unit" : "كيلوجرام",
    "length" : 1,
    "width" :1,
    "height" :1,
    "contents" : "منتج من نوع ما"
  }
}

بعد إرسال الطلب، ستتلقى استجابة تحتوي على معرّف الطلب Order ID الذي تم تسجيله وبيانات أخرى.

{
  "id": 103,
}

هذا هو معرّف الطلب id الذي ستستخدمه لاحقًا في عمليات الدفع والتحويل المتعلقة بالطلب.

“اقرأ أيضاً: شرح استخدام FlutterToast في Flutter“

الخطوة 3: الحصول على مفتاح الدفع payment token

في هذه الخطوة، سنقوم بإعداد تحويل الدفع لإتمام عملية الدفع الفعلية. ستحتاج إلى استخدام معرّف الطلب id الذي تم تسجيله في الخطوة السابقة للحصول على payment_key token.

يتم إرسال طلب التسجيل الى “https://accept.paymob.com/api/acceptance/payment_keys” كطلب POST ويحتوي على كائن JSON يحتوي على المعلومات المطلوبة لتسجيل الطلب، مثل معرّف الطلب id الذي حصلنا عليه في العملية السابقة.

بيانات الطلب المطلوبة:

{
  "auth_token": "ZXlKaGlPaUpJVXpVeE1pSX1Y0NJmV5Sn...",  // من الخطوة 1
  "amount_cents": "100",  // السعر بالقروش
  "expiration": 3600, // وقت انتهاء صلاحية رمز الدفع هذا بالثواني. (الحد الأقصى هو 3600 ثانية وهي ساعة)
  "currency": "EGP",  // العملة جنية مصري
  "order_id": 103,  // من الخطوة 2
  "integration_id": 100, // معرّف لقناة الدفع التي تريد أن يقوم عميلك بالدفع من خلالها يوجد في حسابك.
  "billing_data": {
    "apartment": "803", 
    "email": "claudette09@exa.com", 
    "floor": "42", 
    "first_name": "Clifford", 
    "street": "Ethan Land", 
    "building": "8028", 
    "phone_number": "+86(8)9135210487", 
    "shipping_method": "PKG", 
    "postal_code": "01898", 
    "city": "Jaskolskiburgh", 
    "country": "CR", 
    "last_name": "Nicolas", 
    "state": "Utah"
  }, 
  "lock_order_when_paid": "false"
}

بعد إرسال الطلب، ستتلقى استجابة تحتوي على مفتاح الدفع payment token الذي ستستخدمه في الدفع.

{
  "token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6VX..."
}

إذن، هذه هي الخطوات الأساسية المطلوبة لبدء أي عملية دفعة من خلال أي من قنوات الدفع المتاحة.

“اقرأ أيضاً: شرح استخدام url_launcher في Flutter“

الدفع باستخدام الكيوسك Kiosk:

يجب أن تقوم بإرسال طلب الدفع إلى “https://accept.paymob.com/api/acceptance/payments/pay” كطلب POST ونوع المحتوى JSON.

يتطلب طلب الدفع معاملين رئيسيتين: “source” و “payment_token”. يجب توفير رمز المصدر الذي يحدد قناة الدفع المستخدمة، ورمز الدفع الذي تم الحصول عليه من الخطوة الثالثة بالأعلى.

{
  "source": {
    "identifier": "AGGREGATOR", 
    "subtype": "AGGREGATOR"
  },
  "payment_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6VX..." // من الخطوه 3
}

بعد إرسال طلب الدفع بنجاح، ستتلقى استجابة JSON تحتوي على معلومات حول العملية. إذا كان الطلب ناجحًا، ستحتوي الاستجابة على “pending”: true و “success”: false، مما يعني أن العملية تم إنشاؤها ولكنها في انتظار الدفع. يجب عرض رسالة للعميل تحتوي على قيمة “bill_reference” من ال”data”. يجب أن تطلب الرسالة من العملاء أن يستفسروا عن “Madfouaat Mutanouea Accept” وإعطاء الرقم المرجعي الخاص بهم.

هذه البيانات الراجعة من الresponse

{
  "id": 580,
  "pending": "true",
  "amount_cents": 100,
  "success": "false",
  "is_auth": "false",
  "is_capture": "false",
  "is_standalone_payment": "true",
  "is_voided": "false",
  "is_refunded": "false",
  "is_3d_secure": "false",
  "integration_id": 35,
  "profile_id": 1,
  "has_parent_transaction": "false",
  "order": 103,
  "created_at": "2018-04-18T12:29:43.523592",
  "transaction_processed_callback_responses": [],
  "currency": "EGP",
  "source_data": {
      "pan": "",
      "type": "aggregator",
      "sub_type": "AGGREGATOR"
  },
  "api_source": "OTHER",
  "is_void": "false",
  "is_refund": "false",
  "data": {
      "amount": "null",
      "gateway_integration_pk": 35,
      "agg_terminal": "null",
      "klass": "CAGGPayment",
      "rrn": "null",
      "due_amount": 100,
      "ref": "null",
      "message": "Pending Payment",
      "txn_response_code": "05",
      "biller": "null",
      "bill_reference": 580, // this is the reference that the client will ask for at Accept Kiosk Partner outlets
      "from_user": null
  },
  "is_hidden": "false",
  "payment_key_claims": {
      "currency": "EGP",
      "amount_cents": 100,
      "integration_id": 35,
      "order": 103,
      "user_id": 2
  },
  "error_occured": "false",
  "is_live": "false",
  "other_endpoint_reference": "null",
  "refunded_amount_cents": 0,
  "is_captured": "false",
  "captured_amount": 0,
  "merchant_staff_tag": "null",
  "owner": 2,
  "parent_transaction": null
}

في النهاية، بعد اكتمال تكاملك مع Kiosk Payments في Paymob، يجب عليك تهيئة endpoints لاستقبال إشعارات الدفع من خادم Paymob.

“اقرأ أيضاً: شرح استخدام ويدجت ListTile في فلاتر“

الدفع باستخدام البطاقة Card Payments:

يمكنك استخدام واجهة برمجة التطبيقات (API) لـ Paymob لقبول المدفوعات باستخدام بطاقات الائتمان على موقع الويب أو التطبيق المحمول الخاص بك.

هذه الطريقة عبارة عن رابط سيتم عرضه داخل التطبيق باستخدام حزمة webview_flutter ولكن هذا الرابط لإطار العرض (iFrame) الذي يمكنك استخدامه لتضمين نافذة الدفع على موقعك أو تطبيقك. يجب توفير معرف الإطار (iFrame ID) من حسابك ورمز الدفع (Payment Token) الذي تم الحصول عليه من الخطوة الثالثة في عملية الحصول على مفتاح الدفع.

بعد تهيئة إطار العرض بنجاح، يمكنك استخدام بيانات الاختبار المقدمة في الدليل لإجراء عملية اختبار باستخدام بطاقة MasterCard. يجب استخدام البيانات التالية لإجراء الاختبار:

• رقم البطاقة: 5123456789012346
• اسم حامل البطاقة: Test Account
• شهر الانتهاء: 12
• سنة الانتهاء: 25
• رمز التحقق:123

بعد اكتمال تكاملك مع Card Payments في Paymob، يجب عليك تهيئة endpoints لاستقبال إشعارات الدفع من خادم Paymob. يمكنك الاطلاع على الدليل المرفق في الرابط التالي لمعرفة المزيد حول إشعارات الدفع: https://docs.paymob.com/docs/transaction-callbacks.

ملحوظة: لاستخدام الدفع بهذه الطريقة يجب التواصل مع الدعم واعطائهم integration_id الخاص بهذه الطريقة ليتم تفيعلها والا سيظهر لك خطا في نهاية كل عملية دفع حتى لو كانت البيانات صحيحة.

“اقرأ أيضاً: شرح استخدام ويدجت AlertDialog في فلاتر“

الدفع باستخدام المحفظة (Mobile Wallets):

الآن بعد أن حصلت على مفتاح الدفع من الخطوة 3، تحتاج إلى إعداد الدفع الخاصة بك. تتيح لك واجهة برمجة التطبيقات (API) الخاصة ب Paymob قبول الدفع على موقع الويب أو التطبيق الخاص بك.

يجب أن تقوم بإرسال طلب الدفع إلى “https://accept.paymob.com/api/acceptance/payments/pay” كطلب POST ونوع المحتوى JSON.

{
  "source": {
    "identifier": "رقم الهاتف المرتبط بالمحفظة",
    "subtype": "WALLET"
  },
  "payment_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6VX..." // من الخطوه 3
}

استجابة طلب الدفع

{
  "id":78,
  "pending": "true",
  "amount_cents":1000,
  "success":"fasle",
  "is_auth": "false",
  "is_capture": "false",
  "is_standalone_payment":"true",
  "is_voided": "false",
  "is_refunded": "false",
  "is_3d_secure": "false",
  "integration_id":1,
  "profile_id":1,
  "has_parent_transaction": "false",
  "order":{
    "id":103,
    "created_at":"2016-12-26T06:49:16.651010Z",
    "delivery_needed": "false",
    "merchant":{
      "id":1,
      "created_at":"2016-11-17T15:02:53.646620Z",
      "phones":[
        "011111111111",
        "012324151432"
      ],
      "company_emails":[
        "brendon42@cummings-windler.biz",
        "jim50@sipes-kunze.com"
      ],
      "company_name":"Wuckert, Zieme and Dach",
      "state":"Oklahoma",
      "country":"Oman",
      "city":"Port Arvillachester",
      "postal_code":"83372",
      "street":"Walker Ramp"
    },
    "collector": "null",
    "amount_cents":1000,
    "shipping_data":{
      "id":73,
      "first_name":"Clifford",
      "last_name":"Nicolas",
      "street":"Ethan Land",
      "building":"8028",
      "floor":"42",
      "apartment":"803",
      "city":"Jaskolskiburgh",
      "state":"Utah",
      "country":"CR",
      "email":"claudette09@exa.com",
      "phone_number":"+86(8)9135210486",
      "postal_code":"01898",
      "extra_description":"",
      "shipping_method":"UNK",
      "order_id":94,
      "order":94
    },
    "currency":"EGP",
    "is_payment_locked":"true",
    "merchant_order_id": "null",
    "wallet_notification": "null",
    "paid_amount_cents":0,
    "items":[]
  },
  "created_at":"2016-12-26T06:49:16.680871Z",
  "transaction_processed_callback_responses":[],
  "currency":"EGP",
  "source_data":{
    "number": 01274155230,
    "sub_type": "WALLET",
    "type": "wallet"
  },
  "error_occured": "false",
  "owner": 2,
  "parent_transaction": "null",
  "redirect_url": "this_is_the_wallet_redirect_url"  // هذا الرابط هو المطلوب
}

يتم توجيه العميل لرابط التوجيه redirect_url المرسل في استجابة طلب الدفع. سيتم عرض تجربة الدفع الخاصة بالمحفظة المستخدمة.

يجب تجهيز endpoints لاستقبال تنبيهات المعاملة من خادم Paymob بعد اتمامها.

“اقرأ أيضاً: كيفية تثبيت Flutter على نظام ويندوز 2023“

الخلاصه:

تلخيص السيناريو اللي بيحصل إن أنت عندك متجر مثلا وأكيد المستخدم ليه حساب عليه يعني أنت كدا معاك الاسم والايميل ورقم الموبايل لأن دا هتحتاجه لو هيدفع فودافون كاش وطبعا لازم يكون هيكون معاك السعر أو هو هيدفع كام… دي كدا البيانات الأساسية.

اللي أنت كمبرمج هتعمل هو انك لازم تعمل الخطوة رقم 1 في بداية عملية الشراء للحصول على الـ auth token وبعد كدا تنفذ الخطوة رقم 2 اللي بيكون فيها معلومات عملية الشراء والمنتجات والسعر… الخ وفي الخطوة دي هتحصل على معرف فريد خاص بالطلب… دا هتستخدمه في الخطوة رقم 3 اللي منها هتحصل على مفتاح الدفع payment token اللي هتستخدمه بعد كدا سواء المستخدم هيدفع فيزا أو فودافون كاش. ولكن خلي بالك ان integration_id الخاص بالدفع بالفيزا غير الخاص بفودافون كاش ودا موجود في الخطوة 3 وتقدر تحصل على كل واحد فيهم من حسابك هنا.

دلوقتي أنت معاك مفتاح الدفع payment token تقدر تستخدمه لو هتدفع بالفيزا عن طريق وضعه في الرابط وعرضه webview ذي م شرحنا فوق… لكن لو هتستخدم الدفع بفودافون كاش هتستخدمه مع رقم الموبايل الأول وهنا هيظهرلك رابط خاص بفوادفون كاش تقدر تعرضه عادي webview يعني خطوه زيادة.😊

وهنا هتلاقي مشروع مرفوع على GitHub في الكود عبارة عن فورم للتسجيل علشان أخد البيانات وبعد كدا المستخدم يختار طريقة الدفع ويكمل باقي الموضوع “المشروع هنا“.

تعد بطاقات الفيزا ومحافظ الكاش الإلكترونية مثل فودافون كاش وسيلة دفع شائعة وموثوقة في عالم التجارة الإلكترونية. تسهل خدمة فودافون كاش عملية الدفع وتوفر راحة وأمانًا للمستخدمين أثناء التسوق عبر الإنترنت.

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