يعمل مفتاح API الدفع كبطاقة نقدية بلا رقم سري. فمن يرسله يستطيع إنشاء الفواتير وقراءة بيانات الدفع الخاصة بك، وإذا كنت تستخدم المدفوعات الصادرة، فيمكنه أيضاً نقل الأموال خارج رصيدك. لذلك يتلخص أمان API الدفع في ثلاث عادات: الاحتفاظ بالمفتاح على خوادمك، والسماح لـ API بقبوله من عناوين تلك الخوادم وحدها، والتأكد من كل Webhook بقراءة الدفعة مرة أخرى قبل التصرف بناءً عليها.
يُعد هذا الدليل موجهاً لقادة الهندسة ورؤساء المدفوعات لدى مزودي خدمات الدفع (PSPs) ومؤسسات النقود الإلكترونية (EMIs) والبنوك والتجار الذين يربطون API دفع بالعملات المشفرة يتم تسويته باليورو. ويوضح كيفية تقييد المفتاح حسب عنوان IP ونطاق CIDR، وأين ينبغي حفظ المفتاح، وكيفية التحقق من Webhooks، وأي ضوابط ينبغي وضعها حول المدفوعات الصادرة. تستند الأمثلة إلى API ولوحة تحكم ItisPay (بيانات تجريبية).
اللحظات الرئيسية
باختصار
- مفتاح API هو بيانات اعتماد من نوع bearer، أي أن من يحمله يُعامَل كمُصرَّح له. رصدت GitGuardian 28.65 مليون سرّ جديد مُضمَّن في الكود (hardcoded) ضمن عمليات الإيداع العامة على GitHub في عام 2025، لذا خطط لاحتمال تسرب المفتاح، لا للحفاظ عليه فقط.
- تجعل قائمة IP المسموح بها المفتاح المُسرَّب عديم الفائدة خارج شبكتك. اذكر أصغر نطاقات IPv4 أو IPv6 التي تغطي عناوينك الصادرة الفعلية؛ والقائمة الفارغة تسمح بكل العناوين.
- الـ Webhook إشعار، وليس دليلاً. أعد قراءة الفاتورة بمعرّفها باستخدام مفتاحك قبل أن تشحن البضائع أو تضيف رصيداً إلى حساب.
- تحتاج المدفوعات الصادرة إلى ضوابط بشرية من جانبك: تسجيل دخول بخطوتين، وحفظ IBANs ومحافظ المستفيدين، ومُعتمِد ثانٍ فوق مبلغ محدد.
لماذا يُعد تسرب مفتاح API الدفع خطيراً إلى هذا الحد؟#
يُعد تسرب مفتاح API الدفع خطيراً لأن المفتاح يمثّل هوية تكاملك بالكامل. يوثّق API الخاص بـ ItisPay، شأنه شأن معظم واجهات الدفع، كل طلب برأس واحد هو Api-key، وتغطي هذه المصادقة نفسها الفواتير والمدفوعات الصادرة إلى IBAN أو محفظة، وعمليات سحب العملات المشفرة إلى عنوان خارجي. ولهذا تطلب الوثائق ألا يكون المفتاح "مكشوفاً في الكود من جهة العميل أو في المستودعات العامة".
يتسرب المفتاح عادةً عبر أماكن عادية: الكود وسجلات الأحداث (logs) والمحادثات. ووفقاً لتقرير حالة انتشار الأسرار لعام 2026 لدى GitGuardian (مارس 2026)، أُضيف 28.65 مليون سرّ جديد مُضمَّن في الكود إلى عمليات الإيداع العامة على GitHub في عام 2025، بزيادة 34% عن العام السابق. وعندما أعادت GitGuardian اختبار الأسرار المسرّبة في عام 2022، ظل أكثر من 64% منها صالحاً في يناير 2026. فالفرق تنشر المفاتيح ثم تنسى استبدالها.
تصنّف OWASP API Security Top 10 (2023) مشكلة "Broken Authentication" في المرتبة الثانية، وتحذر من أن "آلية المصادقة هدف سهل للمهاجمين لأنها مكشوفة للجميع". ويذكر تقرير Verizon لتحقيقات خروقات البيانات لعام 2025 أن إساءة استخدام بيانات الاعتماد هي أكثر ناقل هجوم أولي شيوعاً، بنسبة 22%. وسلسلة نصية سرية وحدها دفاع هش، لذلك يضيف بقية هذا الدليل طبقات تظل صامدة بعد خروج السلسلة إلى العلن.
كيف تحمي قائمة IP المسموح بها مفتاح API؟#
تحمي قائمة IP المسموح بها، وتُسمّى أحياناً القائمة البيضاء لعناوين IP، المفتاح بربطه بالأماكن إلى جانب ربطه بسلسلة نصية. يقبل API المفتاح فقط عندما يأتي الطلب من عنوان أدرجته؛ أما نسخة من المفتاح على حاسوب مطور أو في سجل CI أو على موقع لصق النصوص فلا تعمل.
في لوحة تحكم ItisPay يقع هذا الإعداد تحت Projects ثم Settings ثم Security، في الحقل API Allowed IPs. يقبل الحقل قائمة مفصولة بفواصل من عناوين مفردة وكتل CIDR. ويقول نص المساعدة فيه: "اتركه فارغاً للسماح بكل عناوين IP. ويُدعم كل من IPv4 وIPv6." ويمكن ضبط القائمة نفسها عند إنشاء المشروع عبر API في الحقل api_allowed_ips، وتُرفض الإدخالات غير الصالحة مثل 256.256.256.256 بخطأ تحقق بدلاً من حفظها.
الإعداد الافتراضي الفارغ مهم. فالمشروع الجديد يقبل مفتاحه من أي مكان إلى أن يملأ أحد الحقل، لذا ضع هذه الخطوة في قائمة ما قبل الإطلاق، لا في قائمة الأمور التي تُرتَّب لاحقاً. والقيم التجريبية في الصورة، أي 203.0.113.10 و198.51.100.0/24، تأتي من نطاقات تحجزها RFC 5737 للتوثيق؛ أما قائمتك فستحتوي على عناوينك العامة الخاصة. ولكل مشروع مفتاحه الخاص المكوّن من 64 حرفاً وقائمته الخاصة، لذا يمكن أن يبقى الإنتاج مقفلاً على خادمين أو ثلاثة بينما يقبل مشروع الاختبار مجموعة أوسع.
كيف تكتب نطاقات CIDR لـ IPv4 وIPv6؟#
اكتب أصغر نطاق يغطي كل عنوان تستخدمه خوادمك فعلياً للوصول إلى API. وأغلب مشكلات قوائم السماح تنشأ من نطاق أوسع بكثير مما ينبغي، أو من مسار صادر نسيه أحدهم.
قراءة البادئة#
كتلة CIDR عنوان يتبعه شرطة مائلة وطول بادئة. وتُعرّف RFC 4632 طول البادئة بأنه عدد البتات المعنوية: فالنطاق 192.168.99.0/24 يثبّت أول 24 بتاً ويترك 8 بتات حرة، أي 256 عنواناً. وكل بت تُنقصه من البادئة يضاعف الكتلة. فـ /32 عنوان IPv4 واحد، و/29 يضم 8 عناوين، و/24 يضم 256، و/16 يضم 65,536.
يعمل IPv6 بالطريقة نفسها بـ 128 بتاً. فـ /128 عنوان واحد. وتضع RFC 4291 جزء الواجهة في معظم عناوين IPv6 عند 64 بتاً، لذا تكون شبكة الخادم عادةً /64 ويمكن للمضيف أن يغيّر عنوانه داخلها، مثلاً عندما يولّد نظام التشغيل عناوين مؤقتة. فإذا تغيّر عنوان IPv6 لمضيفك وكانت تلك /64 لك وحدك، فأدرج /64 بدلاً من /128 مفرد. ونطاق التوثيق لأمثلة IPv6 هو 2001:db8::/32 (RFC 3849)، فلا تنسخه أبداً إلى قائمة سماح حقيقية.
إيجاد عنوان الصادر الحقيقي#
العنوان المهم هو العنوان الذي يراه API، لا العنوان الذي يبلّغ عنه خادمك عن نفسه. فخلف بوابة NAT سحابية أو جدار حماية للشركة، تتشارك أجهزة كثيرة عنواناً عاماً أو اثنين. وغالباً ما تخرج الدوال بلا خادم (Serverless) من مجموعة مشتركة ما لم توجّهها عبر مخرج ثابت. تحقّق من كل بيئة باستدعاء خدمة "ما هو عنواني IP"، أو اقرأ عنوان المصدر من سجلات جدار الحماية، ثم أدرج هذا العنوان تحديداً.
| الإعداد | ما يُدرج في القائمة | الحكم |
|---|---|---|
| خادم واحد بعنوان IPv4 عام وثابت | هذا العنوان بصيغة /32 أو كما هو | يعمل |
| عدة خوادم خلف بوابة NAT سحابية | عناوين بوابة NAT العامة | يعمل |
| مضيف IPv6 تتغير عناوينه | الشبكة /64 الخاصة بالمضيف، إن لم يستخدمها أحد غيره | يتوقف على الحالة |
| شبكة مكتب للاختبار اليدوي | العنوان الثابت للمكتب، إذا كان المزود يضمنه | يتوقف على الحالة |
| دوال بلا خوادم دون مخرج ثابت | وجّهها أولاً عبر NAT بعنوان ثابت | لا |
| النطاق الإقليمي الكامل لمزود السحابة | لا شيء؛ فهو يشمل عملاء آخرين أيضاً | لا |
قبل حفظ أي تغيير، أضف العنوان الجديد أولاً، ثم انشر التحديث، وتأكد من أن الحركة تمر، ولا تحذف القديم إلا بعد ذلك. فحفظ قائمة تستثني خوادمك العاملة يحجب عملية الدفع لديك نفسها.
أين يجب أن يُحفظ مفتاح API، ومن يطّلع عليه؟#
يجب أن يبقى المفتاح على خوادمك، في مخزن أسرار، وفي أي مكان آخر لا. لا تُضمّنه أبداً داخل صفحة متصفح أو تطبيق للهاتف المحمول، لأن أي شخص يستطيع قراءته هناك. وأبقِه خارج عناوين URL أيضاً: فورقة OWASP REST Security Cheat Sheet تحذّر من أن المفتاح الموجود في عنوان URL قد يُلتقط في سجلات خادم الويب. تتحدث صفحة الدفع لديك مع الواجهة الخلفية، والواجهة الخلفية تتحدث مع واجهة برمجة الدفع.
حمّل المفتاح من مدير الأسرار أو من متغيرات البيئة عند بدء التشغيل، لا من ملف إعدادات داخل المستودع. وإذا كنت تستضيف الشيفرة على GitHub، ففعّل حماية الدفع (push protection): وفقاً لوثائق GitHub، عندما “يكتشف سراً محتملاً أثناء محاولة الدفع، فسيحجب الدفع.”
احتفظ بمفتاح مستقل لكل بيئة. كل مشروع في ItisPay يحمل مفتاحه وقائمة السماح الخاصة به، لذا فإن فصل مشاريع الإنتاج عن الاختبار يعني أن المفتاح المسرّب من بيئة الاختبار لا يمكنه المساس بالمدفوعات الحية. قيّد من يستطيع الاطلاع على مفتاح الإنتاج. وتضع إرشادات EBA لعام 2019 بشأن أمن تقنية المعلومات والاتصالات (ICT) قاعدة “الحاجة إلى المعرفة” مع “الحد الأدنى من حقوق الوصول”، ويشمل ذلك المستخدمين التقنيين؛ ومنذ عام 2025 يحمّل DORA هذا الواجب على معظم شركات المدفوعات.
ثم دوّن كيف ستستبدل المفتاح، قبل أن تحتاج إليه. تنص ورقة OWASP Cryptographic Storage Cheat Sheet على تدوير المفاتيح بعد فترة محددة، وكلما اشتُبه في اختراقها، وعلى التأكد من “أن تكون الشيفرة والإجراءات اللازمة لتدوير المفتاح قائمةً قبل الحاجة إليها.”
كيف تتحقق من Webhooks القادمة من واجهة برمجة الدفع؟#
تعامل مع Webhook بوصفه إشعاراً بأن شيئاً قد تغيّر، لا بوصفه دليلاً على أنك استلمت أموالك. فأي شخص يعرف عنوان callback URL الخاص بك يمكنه أن يرسل إليه رسالة مزيفة بعبارة “completed”. والنمط الآمن هو أن تقرأ الفاتورة من الواجهة باستخدام مفتاحك، وأن تتصرف وفق ما تعيده الواجهة.
عند إنشاء فاتورة في ItisPay، يحدد الحقل callback_url العنوان الذي تُرسل إليه تحديثات الحالة. وعند وصول Webhook، خذ معرّف الفاتورة منه، ونفّذ طلب GET على الفاتورة بمعرّفها، ولا تشحن البضاعة أو تُودع المبلغ في الحساب إلا إذا أظهرت الاستجابة الحالة التي تتوقعها والمبلغ الذي سعّرته. وتصف الوثائق هذه النقطة النهائية بأنها تُرجع حالة الدفع وتفاصيل البلوكتشين “لعرضها على المستخدمين أو للتحقق”.
بعض القواعد تُبقي معالج الأحداث نظيفاً:
- اقبل Webhooks عبر HTTPS فقط، وارفض HTTP العادي.
- اجعل المعالج idempotent: احفظ معرّف كل فاتورة تمت معالجتها وحالتها، وتجاوز التكرار، لأن المزودين يعيدون إرسال الإشعارات.
- استجب بسرعة ونفّذ العمل في طابور، حتى لا تؤدي قاعدة بيانات بطيئة إلى تفعيل إعادة المحاولات.
- إذا وقّع المزود على Webhooks الخاصة به باستخدام HMAC، وهو تجزئة مفتاحية معرّفة في RFC 2104، فأعد حساب التوقيع وقارنه بدالة ذات زمن ثابت. وتقول OWASP Webhook Security Cheat Sheet الأمر بصراحة: “Never use ==: it leaks timing information and can turn the endpoint into a signing oracle.” وارفض الرسائل التي يكون الطابع الزمني الموقّع فيها قديماً أكثر من اللازم.
اختبر قبل الإطلاق. لدى ItisPay نقطة نهائية تحاكي تغيير الحالة لفاتورة اختبار حقيقية، وأخرى تعيد إرسال آخر Webhook لفاتورة أو لمعرّف طلب، حتى تتحقق من إعادة المحاولات والتكرارات دون أموال حقيقية.
كيف تُحكم السيطرة على عمليات الصرف وعلى الوصول إلى لوحة التحكم؟#
هنا تتحول سرقة المفتاح إلى خسارة للأموال، لذا أضف ضوابط بشرية حول عمليات الصرف. عبر نقطة نهاية payouts في ItisPay، تُرسل عملية الصرف بالعملة الورقية (fiat) إلى IBAN المستفيد، وتُرسل عملية الصرف بالعملات المشفرة إلى عنوان محفظة، وكلتاهما من رصيدك المتاح. تنفّذ الواجهة ما يطلبه الطلب حرفياً؛ أما تحديد ما إذا كان الطلب مشروعاً فهو مسؤوليتك.
ضوابط تعمل من جهتك:
- تسجيل دخول بخطوتين لكل من يملك صلاحية الوصول إلى لوحة التحكم أو الصرف. يعتمد قانون المدفوعات الأوروبي هذه الفكرة بالفعل للمستخدمين في المدفوعات: إذ تشترط قواعد PSD2 بشأن المصادقة القوية للعميل عنصرين مستقلين على الأقل من: المعرفة، والحيازة، والسمة الذاتية (inherence). طبّق المعيار نفسه على موظفيك.
- المستفيدون المحفوظون. احتفظ بقائمتك الخاصة من IBANs ومن عناوين المحافظ المعتمدة، ودع خدمة الصرف لديك ترسل فقط إلى المدخلات الموجودة فيها. ويخضع المستفيد الجديد لموافقة منفصلة، ويفضَّل أن تكون معها فترة تريث.
- معتمِد ثانٍ فوق حد معيّن. شخص يُعد العملية، وآخر يعتمدها. حدّد المبلغ وفق مستوى المخاطرة الذي تقبله.
- خدمة صرف منفصلة. شغّل عمليات الصرف من خدمة واحدة لها عنوانها الثابت الخاص في قائمة السماح، منفصلة عن خوادم الدفع التي تنشئ الفواتير.
| الضابط | ما الذي يمنعه | التقييم |
|---|---|---|
| القائمة المسموحة لعناوين IP على المفتاح | استخدام مفتاح مسرّب من خارج شبكتك | فعّال |
| المفتاح على الخادم فقط | سرقة المفتاح من المتصفحات والتطبيقات والمستودعات | فعّال |
| إعادة قراءة الفاتورة بعد webhook | إشعارات «مدفوع» مزيفة | فعّال |
| المستفيدون المحفوظون والمعتمِد الثاني | تحويلات إلى IBAN أو محفظة يملكها المهاجم | فعّال |
| أيٌّ من هذه الضوابط وحدها ضد خادم مخترق داخل القائمة | سرقة من شخص موجود بالفعل داخل النظام | لا |
ماذا يتوقع DORA وPCI DSS من الوصول إلى API؟#
إذا كنت شركة مالية أوروبية خاضعة للتنظيم، فهذه الضوابط ليست إضافات اختيارية. يُطبَّق قانون المرونة التشغيلية الرقمية (DORA، اللائحة (EU) 2022/2554) منذ 17 يناير 2025، وفقاً لـ EBA. تطلب المادة 9 منه من الشركات «تطبيق سياسات تحدّ من الوصول المادي أو المنطقي» إلى أصول تكنولوجيا المعلومات والاتصالات (ICT)، و«تطبيق سياسات وبروتوكولات لآليات المصادقة القوية». ويُعدّ مفتاح مدرج في قائمة مسموحة، ويكون على الخادم فقط، مع خطة لتدويره، نوعاً من الأدلة التي يطلب المدقق الاطلاع عليها.
يغطي معيار أمن بيانات صناعة بطاقات الدفع (PCI DSS) بيانات البطاقات، لا فواتير العملات المشفرة. وإذا كان الفريق نفسه يدير مدفوعات بالبطاقات أيضاً، يطلب المتطلب 8.4.2 المصادقة متعددة العوامل على كل وصول إلى بيئة بيانات حامل البطاقة، وأصبحت المتطلبات المؤجلة في الإصدار 4.0 إلزامية اعتباراً من 31 مارس 2025.
أين تتوقف ضوابط أمان API للمدفوعات عن العمل؟#
تضيّق هذه الضوابط منافذ الدخول، لكنها لا تجعل التكامل آمناً بمفرده. حتى بالنسبة إلى مُرسِلي webhook، تصف ورقة إرشادات OWASP الخاصة بالـ webhook القائمة المسموحة لعناوين IP بأنها «طبقة إضافية فقط»، لأن «عنوان IP خارجي مشترك ليس دليلاً على الهوية».
أين لا تفيد
- خادم مخترق موجود في القائمة المسموحة. يرسل المهاجم الطلبات من عنوان موثوق باستخدام المفتاح الحقيقي.
- عناوين صادرة مشتركة. إذا كان مستأجرون آخرون يخرجون من السحابة عبر عنوان NAT نفسه، فلا تستطيع القائمة المسموحة التمييز بينهم وبينك.
- كلمة مرور لوحة التحكم المسروقة دون تسجيل دخول بخطوتين. يتجاوز المهاجم الـ API تماماً.
- بيانات شخصية في حقول الفاتورة. تُرجع نقطة النهاية العامة للفواتير في ItisPay التفاصيل كاملة للفواتير المفتوحة دون مفتاح، لذا أبقِ أسماء العملاء وعناوين بريدهم الإلكتروني خارج اسم الطلب.
كيف تبدأ تكاملاً آمناً في فترة بعد ظهر واحدة؟#
يمكنك إنجاز الجانب التقني لتكامل آمن في فترة بعد ظهر واحدة إذا اتبعت ترتيباً ثابتاً. تستخدم الخطوات أدناه ItisPay، ويصلح الترتيب نفسه مع أي مزوّد.
- أنشئ مشروعاً تجريبياً ومشروعاً إنتاجياً منفصلاً، لكل منهما مفتاحه الخاص.
- احفظ المفتاحين في مدير الأسرار لديك، وحمّلهما على الخادم فقط.
- حدّد عنوان IP الصادر العام لكل بيئة وأدخله في حقل API Allowed IPs.
- أنشئ فاتورة من الخلفية: أرسل طلب POST إلى https://api.itispay.com/api/v1/invoices مع ترويسة Api-key، وقيمة order_id فريدة، وfiat_amount مع fiat_currency بقيمة EUR، والعملة المشفرة في الحقل currency، وcallback_url الخاص بك.
- ابنِ معالج webhook: يعمل عبر HTTPS فقط، وهو idempotent، ويعيد قراءة الفاتورة عبر معرّفها قبل أي إجراء.
- شغّل محاكاة webhook لكل حالة تعالجها، ثم نقطة إعادة الإرسال لاختبار التكرار.
- فعّل التحويلات الصادرة في النهاية، مع المستفيدين المحفوظين ومعتمِد ثانٍ.
للبدء بسرعة، يكتب مساعد Ask AI في لوحة التحكم، عند الطلب، نماذج أكواد، مثل استدعاء إنشاء فاتورة بلغة Node.js مع ترويسة Api-key في مكانها. تعامل معها كمسودة: تحقّق من أسماء الحقول مقابل مرجع API قبل النشر، لأن المرجع، لا المثال المولَّد، هو العقد. تنشر ItisPay أيضاً عميل TypeScript الرسمي على npm، وهو @itispay/typescript-client.
إذا كنت تربط هذا بإعداد أوسع لـ تنسيق المدفوعات، فامنح كل مزوّد مفتاحه وقائمته المسموحة ومعالج webhook الخاص به. ويغذّي السجل نفسه الذي يُعاد قراءته بالمعرّف أيضاً مطابقة مدفوعات العملات المشفرة لفريق المالية لديك.
إذا أردت قبول مدفوعات العملات المستقرة وتلقي اليورو دون بناء المنظومة بنفسك، توفر ItisPay واجهة API والفوترة وwebhooks والمطابقة، والطبقة الأولى من أمان API للمدفوعات: مفاتيح يمكنك قصرها على عناوين IP الخاصة بك. ويتم الترخيص وKYC والتسوية إلى IBAN الخاص بك عبر شريكنا المرخّص في الاتحاد الأوروبي (CASP + Payment Institution)، وتنتقل معظم الفرق من KYB إلى أول معاملة في أقل من أسبوع.
هذا المقال لأغراض إعلامية فقط ولا يشكّل مشورة قانونية أو تنظيمية.
