دليل الربط التقني API لبوَّابة سداد: من Sandbox حتَّى الإنتاج في خطوات مرتَّبة.

كم مرَّة فتحت صفحة توثيق بوَّابة دفع جديدة، وبدأت تتلمَّس طريقك بين عشرات الـ endpoints، لتكتشف بعد ساعتين أنَّك كنت تستخدم رمز مصادقة منتهي الصلاحية، أو أنَّ الـ checksumhash لا يتطابق لسبب لا يشرحه التوثيق بوضوح؟

هذا ما يحدث لمعظم المطوِّرين في أوَّل تكامل مع بوَّابة دفع غير مألوفة.

سداد هي بوَّابة دفع قطرية تدعم Visa وMastercard والدفع بوساطة QPAY، وتوفِّر بيئتين منفصلتين تمامًا: Sandbox للتطوير والاختبار، وLive للإنتاج. التكامل معها يمرُّ بمنظومة مصادقة ثنائية المستوى تعتمد Refresh Token وAccess Token، ومسارات عدَّة للدفع تتفاوت في تعقيدها حسب احتياج مشروعك.

هذا الدليل لن يعيد صياغة ما هو موجود في التوثيق الرسمي، بل يأخذك بالترتيب الصحيح: من تفعيل الحساب وبيئة الاختبار، مرورًا بالمصادقة وإنشاء الفواتير، وصولًا إلى Webhook والإنتاج؛ من دون تخمين، ومن دون وقت ضائع.

لنبدأ من الأساسيات…

فَهم بُنية سداد API قبل أي سطر كود.

قبل أن تكتب أوَّل طلب API، يوجد بُنية تحتاج إلى فَهمها فهمًا صحيحًا، لأنَّ معظم الأخطاء التي تواجه المطوِّرين في بداية التكامل لا تأتي من خطأ في الكود، بل من سوء فَهم كيف تعمل المنظومة كاملة.

سداد بوَّابة دفع إلكتروني قطرية تدعم المدفوعات بوساطة بطاقات Visa وMastercard سواء الائتمانية أو الخصم المباشر، إضافةً إلى QPAY وهو نظام الدفع الوطني القطري، فضلاً عن الدفع من رصيد حساب سداد مباشرة. هذا التنوُّع في وسائل الدفع يعني أنَّ مشروعك يصل إلى شريحة أوسع من المُستخدمين في السوق القطرية من دون الحاجة إلى تكاملات متعدِّدة مع جهات مختلِفة.

من الناحية التقنية، تعمل سداد API على بيئتين منفصلتين تمامًا: بيئة Sandbox على sandbox.سدادpay.net مخصَّصة للتطوير والاختبار، وبيئة Live على سدادpay.net للإنتاج. الفرق بينهما ليس في طريقة استدعاء الـ API فحسب، بل في بيانات الاعتماد ذاتها. بيانات Sandbox لا تعمل في الإنتاج والعكس صحيح، وهذا مقصود لأسباب أمنية واضحة. ستحتاج لاحقًا إلى التسجيل في البيئتين والحصول على مفاتيح مستقلَّة لكلٍّ منهما.

أمَّا منظومة المصادقة، فتعتمد مستويين متتاليين لا يمكن تجاوزهما. المستوى الأول هو Refresh Token الذي يُولَّد مرَّة واحدة باستخدام Client ID و Secret Key، ويُعَدُّ طويل العمر نسبيًا. المستوى الثاني هو Access Token الذي يُولَّد من الـ Refresh Token ويُستخدَم في كلِّ طلب API، وعمره أقصر بكثير، وهذا يعني أنَّ تطبيقك يحتاج إلى منطق لتجديده آليًّا عند انتهاء صلاحيته. فكِّر فيهما بوصفهما طبقتين: الأولى تثبت هُوِيَّتك للنظام، والثانية تمنحك تصريح الدخول الفعلي لكلِّ طلب.

يوجد ثلاثة مُعرِّفات جوهرية ستتعامل معها باستمرار في أثناء التكامل، وتجدر الإشارة إليها بوضوح: Client ID وSecret Key وهما مُتاحان في صفحة المِلَفِّ الشخصي لحساب التاجر بعد تفعيل خاصِّية API، وMID أو Merchant ID وهو المُعرِّف الفريد الذي تُصدِره سداد لكلِّ تاجر. 

هذه المُعرِّفات تمثِّل المفاتيح الكاملة للوصول إلى حسابك، ولذلك فالقاعدة الأمنية غير القابلة للتفاوض هي أنَّها لا تُمرَّر أبدًا من جهة العميل، لا في JavaScript في المتصفِّح، ولا في تطبيق الموبايل مباشرةً، بل تبقى حصريًّا على جانب السيرفر. وهذا ليس توصية اختيارية؛ تسريب هذه البيانات يعني أنَّ أي طرف ثالث يستطيع الوصول الكامل إلى بيانات حسابك وعملياتك المالية.

بمجرد أن تستوعب هذه البُنية الثلاثية؛ البيئتان، ومستويا المصادقة، والمعرّفات، ستجد أنَّ بقية التكامل يسير بمنطق واضح ومتَّسق. أنواع بوَّابات الدفع الإلكتروني المتاحة في السوق القطرية تتفاوت في تعقيد تكاملها، وما يميِّز سداد هو وجود توثيق تِقني منظَّم يجعل هذه المرحلة التأسيسية أقلَّ غموضًا ممَّا تبدو عليه في البداية. 

في الفصل الآتي يبدأ من حيث ينبغي أن يبدأ كلُّ تكامل: تفعيل بيئة الاختبار، وفَهم كيف تتحقَّق من أنَّ كلَّ شيء يعمل قبل أن تلمس الإنتاج.

البداية الصحيحة: لا تلمس الإنتاج قبل أن تُتقن Sandbox.

بعد أن فَهمت بُنية سداد API والمعرِّفات التي ستتعامل معها، الخطوة الأولى الفعلية ليست كتابة كود، بل هي إعداد بيئة اختبار حقيقية تحاكي الإنتاج بدقَّة. هذا التمييز مهم: المطوِّرون الذين يتجاوزون Sandbox ويختبرون مباشرةً في الإنتاج يواجهون مشكلة مزدوجة؛ خطأ في الكود يكلِّف معاملات مالية حقيقية، وصعوبة في تشخيص الأخطاء بدون بيانات اختبار آمنة.

للحصول على حساب Sandbox في سداد، سجِّل في sandbox.سدادpay.net، ثمَّ راسل فريق الدعم على [email protected] لتفعيله. بعد التفعيل ستجد Client ID و Secret Key في صفحة المِلَفّ الشخصي  وهذه مختلِفة تمامًا عن بيانات بيئة الإنتاج، لا تخلط بينهما. لتفعيل وضع الاختبار انتقل في لوحة التحكُّم إلى قسم API وشغِّل مفتاح Test Mode.

وهنا يأتي الجزء الذي يوفِّر على كثير من المطوِّرين ساعات من التخمين: سداد توفِّر بطاقات اختبار محدَّدة تعمل حصريًّا في بيئة Sandbox، وفيما يأتي البيانات الكاملة لها كما هي في التوثيق الرسمي:لبطاقة الـ Debit ستُطلَب منك PIN وOTP في أثناء الاختبار، وأي قيمة رقمية تعمل في Sandbox. هذه التفاصيل الصغيرة تبدو بديهية لكن غيابها هو ما يجعل المطوِّر يقضي وقتًا يبحث عن سبب إخفاق المعاملة.

اختبار تحصيل المدفوعات الإلكترونية في Sandbox لا يعني فقط التحقُّق من أنَّ الدفع “يمرُّ”، بل يعني اختبار كلِّ السيناريوهات التي ستواجهها في الإنتاج. معاملة ناجحة، معاملة مخفقة، معاملة مُلغاة من المستخدم في منتصف الطريق، وطلب استرداد. إذا لم تختبر هذه السيناريوهات الأربعة في Sandbox، ستكتشفها لأوَّل مرَّة في الإنتاج، وهو أسوأ وقت ممكن لذلك.

دراسة نشرتها Stripe في مدوَّنة المطوِّرين تشير إلى أنَّ الأخطاء المتعلِّقة بمعالجة حالات الإخفاق تمثِّل ما يزيد على 60% من مشكلات التكامل في بوَّابات الدفع، وهو ما يؤكِّد أنَّ الاختبار الشامل في Sandbox ليس تفصيلًا بل هو جوهر العملية.

حين تنتهي من التحقُّق من كلِّ هذه السيناريوهات في Sandbox، وتكون واثقًا من أنَّ الكود يتعامل تعاملاً صحيحًا مع النجاح والإخفاق على حدِّ سواء، عندها فقط تنتقل إلى بيانات الإنتاج، والخطوة التي تسبق أي دفع حقيقي هي المصادقة، وهي ما سيتناوله الفصل الآتي بالتفصيل.

المصادقة: المفتاحان اللذان يفتحان كلَّ شيء.

حين تنتهي من إعداد بيئة Sandbox وتتأكَّد أنَّ حسابك مفعَّل، تبدأ الرحلة الفعلية مع الكود. وأوَّل شيء ستحتاج إليه قبل أي طلب API، قبل الفواتير، وقبل الدفع، وقبل أي شيء، هو الحصول على Access Token صالح. من دونه، كلُّ طلب ترسله سيعود بخطأ مصادقة.

منظومة المصادقة في سداد تعمل على مرحلتين متتاليتين، وفَهم السبب وراء هذا التصميم يجعل التعامل معه أسهل بكثير.

المرحلة الأولى: توليد Refresh Token.

الـ Refresh Token هو النقطة الأساسية التي تثبت فيها هوية تطبيقك للنظام. تحصل عليه بإرسال طلب POST إلى endpoint التالي:

POST /api/User/GenerateRefreshToken

مع تمرير ClientId وSecretKey في جسم الطلب. الـ Refresh Token الذي تحصل عليه طويل العمر نسبيًّا، وهو ما يعني أنَّك لا تحتاج إلى إعادة توليده في كلِّ جلسة، يكفي تخزينه بأمان في السيرفر، والرجوع إليه عند الحاجة.

المرحلة الثانية: توليد Access Token.

الـ Access Token هو ما ستضعه في header كلِّ طلب API تُرسله. تولِّده من الـ Refresh Token بوساطة:

POST /api/User/GenerateAccessToken

عمره أقصر من Refresh Token بكثير، لذا يحتاج تطبيقك إلى منطق واضح لتجديده آليًّا عند انتهاء صلاحيته، بدلًا من انتظار إخفاق الطلبات لاكتشاف ذلك. الطريقة العملية هي التحقُّق من تاريخ انتهاء الصلاحية قبل كلِّ طلب، وتجديد الـ Token استباقيًّا إذا اقترب من الانتهاء.

فكِّر في الأمر هكذا: الـ Refresh Token هو بطاقة هُوِيَّتك الدائمة التي تثبت أنَّك أنت. والـ Access Token هو تصريح الدخول اليومي الذي يُصدَر بناءً على تلك الهُوِيَّة. البطاقة لا تتغيَّر، لكن التصريح يُجدَّد.

هذا التصميم الثنائي ليس تعقيدًا زائدًا؛ بل هو ممارسة أمنية معيارية في بوَّابات الدفع الحديثة. مبدأ الفصل بين طويل الأمد وقصير الأمد في التوكنات موثَّق على نطاق واسع في هندسة أنظمة المصادقة، وسداد تتَّبعه بنفس المنطق. الفائدة العملية هي أنَّه حتَّى لو اعترض طرف ثالث Access Token منتهي الصلاحية، لن يستطيع استخدامه، ولن يستطيع توليد access token جديد من دون الـ Refresh Token المحفوظ في سيرفرك.

تنبيه أمني لا يقبل المساومة: لا تخزِّن Client ID أو Secret Key أو أي من التوكنين في أي مكان يمكن الوصول إليه من جهة العميل. لا في متغيِّرات JavaScript في المتصفِّح، ولا في كود تطبيق الموبايل كـ hardcoded values، ولا في localStorage. هذه المعرِّفات تمنح وصولًا كاملًا لحساب التاجر وبياناته المالية، وتسريبها يعني تسريب كلِّ شيء. موقع سداد يُشير صراحةً في توثيقه إلى أهمِّية الأمان في منظومة الدفع الإلكتروني بصفتها أولوية غير قابلة للتفاوض في أي تكامل.

بمجرَّد أن يصبح لديك Access Token صالح وآلية لتجديده، أصبح تطبيقك جاهزًا للخطوة التي يُبنَى عليها كلُّ شيء آخر: إنشاء الفاتورة واختيار مسار الدفع المناسب لطبيعة مشروعك، وهو ما يتناوله الفصل الآتي.

ثلاثة مسارات للدفع: أيُّها يناسب مشروعك؟

حين يصبح لديك Access Token صالح، تصل إلى السؤال الذي يحدِّد شكل التكامل بأكمله: كيف ستأخذ المال من العميل؟ سداد توفِّر ثلاثة مسارات مختلِفة، وكلُّ مسار له منطقه ومتطلَّباته التقنية، واختيار المسار الخاطئ يعني إعادة بناء جزء كبير من الكود لاحقًا.

المسار الأول: Payment Invoice  الرابط الذي يُغني عن كثير.

هذا المسار هو الأكثر شيوعًا ولأسباب وجيهة. ترسل طلب POST إلى /api/Invoice/insert مع بيانات الفاتورة، فتحصل على رابط دفع تُرسله إلى العميل مباشرةً. العميل يفتح الرابط ويُكمل الدفع في صفحة سداد، وأنت تستقبل النتيجة في الـ Webhook أو تستعلم عنها لاحقًا بوساطة Payment Status API.

هذا المسار يناسب معظم حالات الاستخدام: متاجر التجارة الإلكترونية، والفواتير المرسلة للعملاء، وطلبات الدفع عند الاستلام، والخدمات التي لا تحتاج إلى تجرِبة دفع مدمجة داخل التطبيق. بساطته التقنية ميزة حقيقية، لا تحتاج إلى معالجة بيانات البطاقة على طرفك، ولا إلى شهادات PCI-DSS إضافية لأنَّ العميل يُدخِل بياناته مباشرةً في صفحة سداد الآمنة.

إذا كنت تبني متجرًا إلكترونيًا في قطر، وتريد البدء بأسرع وقت ممكن، فهذا المسار هو نقطة البداية المنطقية.

المسار الثاني: Embedded Payment  الدفع داخل موقعك بالكامل.

في هذا المسار، العميل لا يغادر موقعك على الإطلاق، أنموذج الدفع يظهر إمَّا Modal Popup وإمَّا iFrame مدمج في صفحتك. تِقنيًا، يتطلَّب هذا المسار خطوتين قبل عرض أنموذج الدفع: أولًا، تسجيل نطاق موقعك بوساطة /api/EmbeddedPayment/allow_domain، وثانيًا، بدء جلسة الطلب بوساطة /api/EmbeddedPayment/intiate_order_session للحصول على رمز الجلسة الذي يُهيئ أنموذج الدفع.

هذا المسار يدعم الدفع بالبطاقات الائتمانية والخصم المباشر وApple Pay وKNet. تنبيه تِقني مهمّ هنا: للبطاقات التي تعمل بـ 3D Secure وبطاقات الخصم المباشر، سيحدث redirect خارجي لصفحة إدخال OTP أو PIN، وهذا سلوك متوقَّع ومقصود وليس خطأً في التكامل، فلا تحاول منعه أو التحايل عليه.

دراسة أجرتها Baymard Institute تُشير إلى أنَّ متوسِّط معدَّل التخلِّي عن سلَّة التسوُّق عالميًا يبلغ نحو 70%، وأنَّ إبقاء المستخدم داخل نفس الواجهة من دون إعادة توجيه يُقلِّل هذا المعدَّل تقليلاً ملحوظًا. هذا ما يجعل Embedded Payment الخِيار الأفضل للمشاريع التي تُولي تجرِبة المستخدم أولوية قصوى وتريد تجرِبة مستخدم سلسة من البداية للنهاية.

المسار الثالث: Web Checkout  للمشاريع التي تحتاج إلى تحكُّم كامل في الأنموذج.

هذا المسار يعتمد أنموذج HTML ترسله مباشرةً إلى https://سدادqa.com/webpurchase في بيئة Sandbox أو https://secure.سدادqa.com/webpurchasepage لنسخة Checkout 2.2. ما يميِّزه تِقنيًا هو اعتماده checksumhash، وهو توقيع رقمي تولِّده بخوارزمية AES-128-CBC على السيرفر من بيانات الطلب مع Secret Key الخاصّ بك.

الـ checksumhash ليس تفصيلًا إضافيًا، هو آلية التحقُّق التي تضمن أنَّ البيانات المُرسَلة من المتصفِّح لم يُعبَث بها بين السيرفر وصفحة الدفع. حين تستقبل الـ callback بعد إتمام الدفع أو إخفاقه، تعيد التحقُّق من الـ checksumhash الوارد مقابل ما تولِّده أنت.، إذا تطابقا، فالاستجابة موثوقة. إذا لم تتطابقا، تجاهلها تمامًا.

Web Checkout 2.2 يضيف خاصِّية عرض أنموذج الدفع داخل iFrame أو Modal Popup داخل موقعك، مشابهًا لـ Embedded Payment، لكن بآلية أنموذج HTML بدلًا من API مباشر،  وهو خِيار مناسب لمَن يريد تجرِبة مدمجة من دون بناء تكامل API كامل من الصفر.

اختيارك بين المسارات الثلاثة يعتمد سؤال واحد: ما مقدار السيطرة التي تريدها على تجرِبة الدفع مقابل مقدار التعقيد التقني الذي يمكنك تحمُّله؟ 

Invoice للبساطة والسرعة، Embedded للتجرِبة المتكاملة، Web Checkout للتحكُّم الكامل في الأنموذج. وبغض النظر عن المسار الذي تختاره، ثمَّة طبقة لا يراها المستخدم لكنها تحدِّد موثوقية الدفع السريع في مشروعك  وهي الـ Webhook، وهو ما سنتناوله في الفصل الآتي.

Webhook وحالة الدفع: الجانب الذي يتجاهله المطوِّرون حتَّى يحترق شيء ما.

اخترت مسار الدفع، وكتبت الكود، وأجريت أوَّل معاملة ناجحة في Sandbox. كلُّ شيء يبدو مكتملًا. لكن يوجد سؤال واحد يكشف إذا كان التكامل محكمًا فعلًا أم لا: ماذا يحدث إذا أكمل العميل الدفع، وانقطع الإنترنت عنده قبل أن يوصله الـ redirect إلى موقعك؟

هذا السيناريو ليس نادرًا. في الواقع، اعتماد الـ callback أو الـ redirect الكامل بوصفه مصدرًا وحيدًا للتحقُّق من حالة الدفع هو أحد أكثر الأخطاء شيوعًا في تكاملات بوَّابات الدفع. المال خرج من حساب العميل، لكن موقعك لم يُسجِّل الطلب بصفة مدفوعاً، ومن هنا تبدأ مشكلة دعم العملاء التي لا تريد أن تعيشها.

كيف يعمل Webhook في سداد؟

Webhook هو طلب HTTP ترسله سداد إلى endpoint في سيرفرك تلقائيًا في اللحظة التي يتمُّ فيها حدث معين، في هذه الحالة، إتمام الدفع. بمعنى آخر: بدلًا من أن يتحتَّم على موقعك انتظار العميل ليعود إليه حاملًا خبر النجاح، سداد تأتي هي إلى سيرفرك مباشرةً لتُخبره بما حدث.

Paid Webhook Event هو الحدث الذي ستستقبله عند إتمام الدفع بنجاح. تحتاج إلى endpoint مخصَّص في سيرفرك يستقبل طلبات POST، ويتحقَّق من صحَّة البيانات الواردة، ويُحدِّث حالة الطلب في قاعدة بياناتك وَفقًا لذلك. هذا الـ endpoint يجب أن يكون متاحًا في الإنترنت، لا يعمل على localhost في الإنتاج بطبيعة الحال، وفي أثناء التطوير يمكنك استخدام أدوات مثل ngrok لتعريضه مؤقَّتًا.

القاعدة التي لا استثناء فيها: تحقَّق دائمًا من السيرفر إلى السيرفر

حتَّى مع Webhook مُعَدٌّ بشكل صحيح، يوجد قاعدة ذهبية في أمان بوَّابات الدفع لا ينبغي تجاوزها: لا تعتمد ما يصل إليك من Webhook أو callback فقط لتأكيد الدفع نهائيًا. بدلًا من ذلك، استخدم حلول الدفع الإلكتروني المتكاملة التي تعتمد التحقُّق المزدوج: حين تستقبل إشعار الدفع، أرسل طلبًا من سيرفرك مباشرةً إلى Payment Status API للتأكُّد من حالة المعاملة بشكل مستقلّ. هذا الاستعلام يكون server-to-server، أي بعيدًا كليًّا عن أي تدخُّل من طرف العميل أو المتصفِّح.

السبب وراء هذه القاعدة بسيط: البيانات القادمة من المتصفِّح يمكن التلاعب بها من مستخدم متمرِّس. البيانات القادمة من سيرفر سداد إلى سيرفرك، بعد التحقُّق من صحَّتها، لا يمكن تزويرها.

رموز الاستجابة التي يجب أن يعرفها كودك.

التوثيق الرسمي يحدِّد أربعة رموز استجابة رئيسة ستتعامل معها في كلٍّ من Webhook والـ callback: الرمز 1 يعني نجاح المعاملة، وهنا تُكمل الطلب وتُرسِل إلى العميل تأكيده. الرمز 400 يعني أنَّ المعاملة معلَّقة Pending ولم تُحسَم بعد، وهنا لا تُلغي الطلب ولا تؤكِّده، بل تنتظر تحديثًا لاحقًا. الرمز 402 يعني أنَّ الدفع في انتظار تأكيد من البنك تحديدًا، وهو مختلِف عن رمز 400 لأنَّه يشير إلى أنَّ العملية وصلت إلى البنك لكن لم تكتمل بعد. الرمز 810 يعني إخفاق المعاملة، وهنا تُعلم العميل وتتيح له المحاولة مرَّة أخرى.

المطوِّر الذي لا يُعالِج الـ 402 معالجة صحيحة، ويتعامل معها بوصفها إخفاقًا فوريًّا، سيُلغي طلباتٍ لم تخفق فعلًا، وسيصل إليه بعدها استفسارات من عملاء دفعوا بالفعل. وهو سيناريو يستحقُّ بعض الوقت في Sandbox لاختباره والتعامل معه تعاملاً صحيحًا.

تقرير نشرته McKinsey عن موثوقية أنظمة الدفع الرقمي يُشير إلى أنَّ المعاملات المعلَّقة وغير المحسومة تمثِّل مصدرًا رئيسًا لنزاعات العملاء في مِنصَّات الدفع، وأنَّ المِنصَّات التي تعتمد تحقُّقًا مُزدوجًا تُقلِّل هذه النزاعات بفرق كبير. هذا بالضبط ما يحميك منه الـ Webhook مُقترنًا بـ Payment Status API.

بعد أن تضمن أن تكاملك يتعامل تعاملاً صحيحًا مع كلِّ حالات الدفع الممكنة، تبقى مسألة واحدة تتعلَّق بسرعة وصولك إلى الإنتاج: الأدوات التي توفِّرها سداد لتسريع التكامل وتقليل الكود الذي تحتاج إلى كتابته من الصفر، وهو ما يتناوله الفصل الأخير.

الأدوات الجاهزة: لا تبنِ من الصفر ما بَنَته سداد لك مسبقًا.

حين تكون واثقًا من أن تكاملك يعالج المصادقة والفواتير والـ Webhook مغالجة صحيحة، يبقى سؤال عملي: هل تحتاج إلى كتابة كلِّ شيء من الصفر؟ في الغالب، لا. إنَّ سداد توفِّر مجموعة من الأدوات الجاهزة التي تختصر وقتًا حقيقيًا في التطوير، وتجاهلها يعني إعادة اختراع ما هو موجود بالفعل.

أوَّل هذه الأدوات وأكثرها فائدة في مرحلة الاختبار هي Postman Collection الجاهزة التي يوفِّرها التوثيق الرسمي. بدلًا من بناء طلبات API يدويًّا وضبط الـ headers واحدًا تلو الآخر، تستورد الـ Collection مباشرةً إلى Postman، تُدخل بيانات اعتمادك، وتبدأ في اختبار كلِّ endpoint فورًا. هذا يعني أنَّك تستطيع التحقُّق من صحَّة تدفُّق المصادقة وإنشاء الفواتير والاستعلام عن حالة الدفع قبل أن تكتب سطرًا واحدًا في مشروعك الفعلي، وهو ما يُسرِّع تشخيص المشكلات تشخيصًا لافتًا.

للمشاريع التي تعمل بـ PHP على جهة السيرفر، توفِّر سداد PHP Library جاهزة تتولَّى معظم تفاصيل توليد الـ checksumhash والتعامل مع الـ responses، وهي تفاصيل يسهل فيها الخطأ حين تبنيها يدويًّا من الصفر. استخدام هذه المكتبة لا يعني فقدان السيطرة على الكود، بل يعني تفويض الجزء الأكثر حساسية من التكامل إلى كود مُختبَر مسبقًا.

أمَّا بالنسبة إلى مَن يبني تطبيقات موبايل، فـ سداد توفِّر Mobile SDK لكلٍّ من Android وiOS بالإضافة إلى Flutter. الـ SDK يتولَّى تقديم واجهة الدفع، ومعالجة الـ callbacks، وإعادة توجيه المستخدم بعد إتمام العملية أو إخفاقها، كلُّ ذلك بكود جاهز يمكنك دمجه في مشروعك. على Android مثلًا، تُعِدُّ البيئة بوساطة سدادService.getProductionService() ثمَّ تُنشِئ المعاملة بوساطة سدادService.createTransaction() مع تمرير بيانات الطلب والـ callback المناسب. رمز الاستجابة 3 في transactionStatusId يعني نجاح المعاملة، والرمز 2 يعني إخفاقها وهذا يختلِف عن رموز الاستجابة في Web API، لذا انتبه إلى هذا الفرق إذا كنت تبني في المِنصَّتين بوقت واحد.

للمشاريع التي لا تحتاج إلى تكامل API كامل من الأساس، كالمتاجر التي تعمل في مِنصَّات جاهزة، توفِّر سداد إضافات مباشرة لأبرز مِنصَّات التجارة الإلكترونية: WooCommerce وShopify وMagento2 وOpenCart وPrestaShop وغيرها. هذه الإضافات تُختصر عملية التكامل كاملًا إلى تثبيت الإضافة وإدخال Merchant ID والـ Secret Key وتفعيل طريقة الدفع، من دون الحاجة إلى التعامل مع API مباشرةً. إذا كنت تبني متجرًا إلكترونيًا في قطر على WooCommerce مثلًا، هذا المسار أسرع بكثير من التكامل اليدوي.

تجدر الإشارة هنا إلى دراسة أجرتها Stack Overflow في تقريرها السنوي للمطوِّرين لعام 2023 والتي أشارت إلى أنَّ المطوِّرين الذين يستخدمون SDKs وأدوات جاهزة يُنجزون مهام التكامل بوقت أقلّ بنسبة تصل إلى 40% مقارنةً بمَن يبنون التكامل من الصفر، وهو رقم يستحقُّ أخذه بالاعتبار حين تُقرِّر أين تُنفِق وقتك التقني.

مهما كانت الأداة التي تختارها، تبقى نقطة واحدة ثابتة في كلِّ مسارات سداد: الجاهزية المالية الرقمية لمشروعك لا تبدأ حين تُطلق الإنتاج، بل تبدأ من جودة التكامل الذي بَنيته وأحكمتَ اختباره. الأدوات الجاهزة تُسرِّع الوصول، لكنَّها لا تُغني عن الفَهم الصحيح لما تحته، وهو ما قرأته في كلِّ قسم من هذا الدليل حتَّى الآن.

من Sandbox إلى الإنتاج: الخطوات الأخيرة قبل أن تستقبل أوَّل ريال حقيقي.

وصلت إلى النقطة التي يصبح فيها التكامل جاهزًا على الورق، المصادقة تعمل، والفواتير تُنشأ، والـ Webhook يستقبل الأحداث، وبطاقات الاختبار تُعيد الرموز الصحيحة. لكن الانتقال من Sandbox إلى الإنتاج ليس مجرَّد تغيير URL وبيانات اعتماد. يوجد قائمة مراجعة قصيرة تفصل بين تكامل محكم وتكامل يُفاجئك بمشكلة في أسوأ وقت ممكن.

أوَّل ما تحتاج إليه هو التأكُّد من أنَّك اختبرت السيناريوهات الأربعة الكاملة في Sandbox قبل المغادرة: معاملة ناجحة، ومعاملة مُخفِقة، ومعاملة ألغاها المستخدم في منتصف الطريق، ومعاملة في حالة انتظار 402. إذا كان كودك يتعامل مع هذه الحالات الأربع تعاملاً صحيحًا؛ يُكمل الناجحة، ويُعيد المحاولة في المُخفِقة، ويتجاهل المُلغاة بأمان، وينتظر المُعلَّقة، فأنت جاهز. إذا لم تختبر واحدة منها، ستكتشفها في الإنتاج على حساب عميل حقيقي.

للانتقال إلى بيئة الإنتاج، تحتاج إلى حساب تاجر مفعَّل في سدادpay.net -وليس Sandbox- مع Client ID وSecret Key مستقلَّين تمامًا عن بيانات الاختبار. بعد تسجيل الدخول في لوحة التحكُّم الفعلية، ستجد هذه البيانات في صفحة المِلَفِّ الشخصي بعد تفعيل خاصِّية API. إذا لم تجدها، راسل فريق الدعم على support@سدادpay.net لتفعيلها. Base URL في الإنتاج يختلِف عن Sandbox، لذا تأكَّد من تحديثه في كلِّ endpoint تستخدمه وليس في مكان واحد فقط.

نقطة يتجاوزها كثير من المطوِّرين في عجلة الإطلاق: تأكَّد من أن Webhook endpoint الخاصّ بك يعمل على HTTPS في الإنتاج، وأنَّ السيرفر يستجيب برمز 200 بعد استقبال الحدث ومعالجته بنجاح. إذا لم يستقبل سيرفر سداد ردًّا 200 في المهلة المحدَّدة، ستُعيد إرسال الـ Webhook، وإذا لم تكن معالجتك للطلبات idempotent، قد تُعالج نفس الدفع مرَّتين. ضع معرِّف المعاملة بوصفه مفتاحًا فريدًا في قاعدة بياناتك، وتحقَّق منه قبل معالجة أي حدث وارد.

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

حين تكون واثقًا من كلِّ ما سبق، الخطوة الأخيرة هي مراجعة التوثيق الرسمي في sadadpay.readme.io للاطلاع على أي تحديثات في الـ endpoints أو تغييرات في هيكل الطلبات، التوثيق يتحدَّث دومًا بصوت أعلى من أي دليل خارجي بما فيه هذا. وللتواصل مع فريق الدعم، لتفعيل الحساب أو حلِّ أي إشكالية، البريد المباشر هو [email protected].

التكامل الجيِّد مع بوَّابة دفع لا يُقاس بعدد الأسطر التي كتبتها، بل بعدد السيناريوهات التي اختبرتها قبل أن يختبرها عميلك الأوَّل بدلًا منك.