العميل دفع ثمن قطعة الغيار ببطاقة مدى، ووصلته رسالة البنك بالخصم، ثم أغلق التطبيق قبل أن تعود صفحة الدفع. بعد ساعة يتصل بالدعم: "دفعت والطلب ما زال غير مدفوع". من المخطئ هنا؟ غالباً ليس البنك ولا البوابة، بل الطريقة التي بُني بها الربط.
الإجابة المختصرة: اختيار البوابة في السعودية أقل أهمية مما تبنيه حولها. استخدم صفحة الدفع المستضافة لدى البوابة، ولا تعتمد على عودة التطبيق من صفحة الدفع كدليل، بل أكّد كل عملية من السيرفر مع البوابة (Webhook واستعلام عن الحالة معاً)، واعتمد الدفعة مرة واحدة فقط، وطابق المبلغ والعملة قبل أن تسلّم أي شيء.
ربطنا ثلاثة أنظمة دفع مختلفة في منتجات تعمل اليوم في السوق: N-Genius من Network International في منصة أجزاء للسيارات، وPayTabs وتابي في تطبيق تكافل الذهبية، وميسر (مع Paymob لمصر) لاشتراكات MONTRA ERP. هذا المقال ليس مقارنة بين البوابات، فقد كتبنا ذلك في دليل اختيار بوابة دفع في السعودية. هنا نتكلم عمّا يحدث بعد توقيع العقد.
المشكلة من جهة صاحب العمل
الدفع الإلكتروني في المملكة له واقع محلي يحدد شكل أي ربط:
- مدى هي البطاقة الأولى. شبكة المدفوعات الوطنية المعتمدة من البنك المركزي السعودي (ساما) وتشغّلها المدفوعات السعودية. صفحة دفع تتعامل جيداً مع فيزا وماستركارد وتهمل مدى تخسر شريحة كبيرة من العملاء.
- Apple Pay متوقَّع من العميل، ببطاقة مدى كما ببطاقة ائتمانية.
- التقسيط منتشر في السلات التي تتجاوز بضع مئات من الريالات، وتابي وتمارا هما الاسمان المعروفان.
- الدفع يتم في صفحة لا تملكها. نموذج البطاقة تستضيفه البوابة، داخل WebView في تطبيقك أو بتحويل من موقعك، وأنت تعرف النتيجة بعد ذلك.
النقطة الأخيرة هي مصدر أغلب المشاكل. طلب مدفوع يظهر عندك غير مدفوع يعني عميلاً غاضباً ومكالمة دعم. وطلب غير مدفوع يظهر مدفوعاً يعني بضاعة خرجت مجاناً. الحالتان تحدثان عندما يصدّق النظام المتصفح بدل أن يسأل البوابة.
هذه الأخطاء لا تظهر في العرض التجريبي، بل في أول أسبوع تشغيل، على شكل استرجاعات واعتراضات.
القرارات التي تتخذها فعلاً
| القرار | الخيارات | ما ننصح به |
|---|---|---|
| أين يُعبّأ نموذج البطاقة | صفحة مستضافة، حقول مدمجة، نموذج خاص بالكامل | الصفحة المستضافة. بيانات البطاقة لا تمر على سيرفراتك، فيبقى نطاق متطلبات PCI صغيراً. |
| كيف تعرف النتيجة | عودة التطبيق، Webhook، استعلام عن الحالة | Webhook مع استعلام. عودة التطبيق مجرد إشارة لبدء التحقق. |
| بوابة واحدة أم أكثر | بوابة واحدة، بوابة لكل سوق، بوابة مع تقسيط | بوابة بطاقات واحدة لكل سوق، مع خدمة تقسيط إن كان متوسط السلة يبرر ذلك. |
| ماذا تدفع الدفعة | جدول دفعات لكل ميزة، أو سجل دفعة واحد يدفع أنواعاً متعددة | نموذج دفع واحد، فكل مسار جديد يستفيد من نفس التحقق. |
| من يقرر أن الطلب مدفوع | تطبيق الجوال أم السيرفر | السيرفر دائماً، بعد تأكيد البوابة. |
اسأل أي جهة تبني لك صفحة الدفع سؤالين: "ماذا يحدث لو دفع العميل وأغلق التطبيق قبل العودة؟" و"ماذا يحدث لو أرسلت البوابة نفس الـ Webhook مرتين؟". الإجابة تكشف لك الكثير.
كيف بنيناه في أجزاء
أجزاء سوق متعدد الأطراف لقطع غيار السيارات وخدماتها يعمل في السعودية: طلبات قطع مباشرة، وطلبات تسعير من المتاجر، وحجز خدمات، وقطع من مورّدين خارجيين، وصيانة متنقلة. يدفع العميل بالبطاقة (مدى وفيزا وماستركارد) أو Apple Pay أو المحفظة داخل التطبيق أو نقداً عند الاستلام. الدفع بالبطاقة وApple Pay يمر عبر N-Genius Online، وهي تذكر في صفحتها للسوق السعودي دعم مدى وفيزا وماستركارد وApple Pay.
شاشة إتمام الطلب في تطبيق العميل مع اختيار طريقة الدفع: بطاقة (شعارات مدى وفيزا وماستركارد) وApple Pay والمحفظة
مسار الدفع باختصار:
- يطلب التطبيق من السيرفر بدء دفعة لطلب أو حجز محدد.
- ينشئ السيرفر سجل دفعة، ثم ينشئ طلباً لدى N-Genius ويستلم رابط صفحة الدفع.
- يفتح التطبيق الرابط في WebView ويراقب العنوان.
- عندما تصل الصفحة إلى رابط العودة، يغلقها التطبيق ويطلب من السيرفر التحقق.
- يسأل السيرفر البوابة عن حالة الطلب. وفي الوقت نفسه ترسل البوابة Webhook. أيهما يصل أولاً يعتمد الدفعة، والثاني لا يفعل شيئاً.
- بعد حفظ المعاملة في قاعدة البيانات، تُنشأ الشحنة لدى شركة الشحن في الخلفية.
سجل دفعة واحد (Payment) يغطي خمسة أنواع مما يمكن أن يدفعه العميل: طلب، طلب تسعير من متجر، حجز خدمة، طلب قطع خارجية، وطلب صيانة متنقلة. التحقق ومعالجة الـ Webhook والاعتماد مكتوبة مرة واحدة، وكل نوع يضيف فقط خطوته الصغيرة: ماذا يحدث عندما يُدفع.
تحت الغطاء: ما يعالجه الكود
نسخة السعودية وقيمة PURCHASE
تشغّل Network International بيئة مستقلة لكل منطقة، ومفاتيح التاجر السعودي تعمل على عنوان KSA فقط. على حسابات التجار في السعودية، قيمة SALE تعود بخطأ 422 saleNotAllowed، لذلك نستخدم PURCHASE التي تفوّض وتحصّل في خطوة واحدة. المبالغ تُرسل بالهللة كأرقام صحيحة.
const payload = {
// KSA outlets reject 'SALE' with 422 saleNotAllowed.
// 'PURCHASE' is single-step authorize + capture.
action: 'PURCHASE',
amount: { currencyCode: 'SAR', value: Math.round(amount * 100) },
merchantOrderReference: payment.referenceNumber,
merchantAttributes: {
redirectUrl: returnUrl,
cancelUrl: `${returnUrl}&cancel=1`,
skipConfirmationPage: true,
},
};
رمز الدخول (Access Token) يُحفظ طوال صلاحيته، 55 دقيقة افتراضياً، ويُجدَّد قبل انتهائه بثلاثين ثانية. هكذا لا ينتظر العميل في صفحة الدفع طلب مصادقة على وشك الفشل.
تأكيدان مستقلان
صفحة العودة ليست دليلاً على الدفع. قد يضيع التحويل أو يتأخر، وقد يصل إليها عميل ألغى. لذلك يستدعي التطبيق نقطة تحقق تسأل البوابة عن الحالة، وفي الوقت نفسه تستدعي البوابة الـ Webhook. المساران ينتهيان في دالة اعتماد واحدة.
App WebView ──► hosted page ──► return URL (?cancel=1 = cancelled)
│ │
│ app calls POST /payments/verify
│ │
│ backend ──► GET order state (N-Genius)
▼ │
N-Genius ──► webhook ──► backend │
\ /
► finalizePayment (once, in a DB transaction)
│
└─► after commit: create shipment (non-blocking)
في التطبيق، يُعاد طلب التحقق كل ثانيتين حتى 15 مرة. صفحة بنك بطيئة أو Webhook متأخر لا يعني أن يرى العميل شاشة فشل.
التحقق من مصدر الـ Webhook
لوحة N-Genius للسوق السعودي تتيح للتاجر تعريف اسم Header وقيمته، تُرسل مع كل Webhook. يقارن السيرفر القيمة بالسر المحفوظ مقارنة ثابتة الزمن:
const expected = Buffer.from(webhookSecret, 'utf8');
const incoming = Buffer.from(headerValue.trim(), 'utf8');
if (expected.length !== incoming.length) return false;
return crypto.timingSafeEqual(expected, incoming);
اعتماد مرة واحدة داخل Transaction
دالة الاعتماد تخرج فوراً إن كانت الدفعة COMPLETED. غير ذلك، تعتمد الدفعة وتحدّث الطلب أو الحجز المرتبط بها في نفس المعاملة، فلا تجد دفعة مكتملة لطلب غير مدفوع. أما ما يتصل بأطراف خارجية، مثل إنشاء الشحنة، فيعمل بعد الحفظ ويسجّل الخطأ دون أن يلغي الدفع. إعادة محاولة الشحنة ممكنة من لوحة التحكم، أما إرجاع مبلغ لأن خدمة الشحن تأخرت فليس حلاً.
حذف طريقة دفع دون كسر السجلات
كانت قائمة طرق الدفع تتضمن STC Pay. عند حذفها، حوّل الـ Migration أولاً السجلات القديمة التي تستخدمها، ثم أعاد بناء الـ Enum في PostgreSQL من دونها. حذف قيمة ما زالت سجلات قديمة تشير إليها يُفشل الـ Migration، والتحويل أولاً يُبقي التاريخ مقروءاً.
كيف بنيناه في تكافل الذهبية
تكافل الذهبية تطبيق بطاقة عضوية وخصومات لشبكة طبية سعودية. يدفع الأعضاء رسوم الاشتراك عبر صفحة PayTabs المستضافة، ومتجر الخدمات الطبية الأحدث يتيح الشراء بتابي.
شاشة الدفع في متجر الخدمات الطبية: التحقق من الهوية مكتمل، ورسالة أهلية تابي، وزر الدفع
مع PayTabs، يفتح التطبيق رابط الدفع في WebView وينتظر صفحة النتيجة. يقرأ قيمة Result فقط ليقرر هل يطلب التأكيد من السيرفر، والإلغاء لا يرسل طلباً. وإن لم تعد الصفحة خلال 5 دقائق، تُغلق تلقائياً حتى لا يبقى العضو أمام صفحة فارغة.
أما متجر تابي فيقوم على قاعدة مكتوبة في عقد الـ API نفسه: حالة الطلب من السيرفر هي التي تقرر النتيجة، لا الـ WebView.
- قبل تفعيل زر الدفع، يسأل التطبيق عن أهلية العميل لتابي. إن رُفضت السلة يبقى الزر معطلاً وتظهر الرسالة. وثائق تابي تصف نفس النمط: فحص مسبق في الخلفية، ثم جلسة كاملة للمؤهلين فقط.
- إنشاء الطلب يعيد معرّفه ورابط تابي. وإعادة المحاولة بنفس البنود تعيد نفس الطلب غير المدفوع ولا تنشئ طلباً مكرراً.
- أثناء فتح تابي، يسأل التطبيق عن حالة الطلب كل 3 ثوانٍ. يتوقف السؤال عندما ينتقل التطبيق للخلفية، ويستأنف بفحص فوري عند العودة.
- إن انتهت الجلسة أثناء الدفع (خطأ 401)، يتوقف السؤال ويُطلب من المستخدم التحقق من هويته مجدداً، بدل أن يبقى عالقاً على "جارٍ التحقق من الدفع".
- كل طلب كتابة يحمل
X-Idempotency-Key.
if (isPaid || status == PaymentStatus.paid) {
_timer?.cancel();
if (_shouldClearCart(order)) await _cart.clearIfPaid(true);
emit(PaymentState(phase: PaymentPhase.paid, order: order));
}
تفصيلتان جاءتا من الاستخدام الفعلي. السلة لا تُفرَّغ إلا عندما يصبح is_paid صحيحاً، وليس عند العودة من صفحة الدفع. ودفع طلب قديم من "طلباتي" لا يفرّغ السلة إلا إن كانت بنوده هي بنود السلة نفسها، حتى لا تضيع سلة يجهزها العميل لشيء آخر.
الضريبة يحسبها السيرفر بعد معرفة الجنسية: صفر للمواطن السعودي و15% لغيره في عقد هذا المتجر. التطبيق لا يحسب أي سعر.
كيف بنيناه في MONTRA ERP
MONTRA ERP نظام SaaS لإدارة عمليات الصيانة يُباع في مصر والسعودية. تدفع الشركة ثمن الباقة ودورة الفوترة. الشركات السعودية تدفع بالريال عبر فاتورة ميسر المستضافة، والمصرية بالجنيه عبر Paymob. تُختار البوابة حسب دولة الشركة خلف واجهة واحدة PaymentProvider، فمنطق الفوترة لا يعرف أي بوابة تعمل تحته.
صفحة الفوترة: الباقة الحالية والاستخدام مقابل الحدود وسجل المدفوعات
التحقق من الـ Webhook يختلف لأن كل بوابة توقّع بطريقتها. Paymob ترسل HMAC-SHA512 محسوباً على قائمة حقول بترتيب ثابت، فنعيد حسابه ونقارنه بـ timingSafeEqual. وميسر تضع في جسم الـ Webhook قيمة secret_token التي تحددها أنت في لوحة التحكم. نتحقق منها، ثم نطلب الفاتورة من API ميسر قبل أن نصدّق حالتها.
بعد ذلك تقوم خطوة التسوية بثلاثة أمور تهم المال:
- تقفل سجل الدفعة (
SELECT ... FOR UPDATE) وتخرج إن كانت مدفوعة، فلا يفعل الـ Webhook المكرر شيئاً. - ترفض الدفعة إن اختلف المبلغ أو العملة المؤكدان عما طلبناه.
- تمدّد الاشتراك من اليوم أو من تاريخ انتهائه الحالي، أيهما أبعد، فالدفع المبكر لا يُضيع أياماً.
وإن كنت تضيف التقسيط إلى متجرك أيضاً، راجع دليل ربط تمارا وتابي بمتجرك.
قائمة تحقق قبل التشغيل مع بوابة سعودية
- اختبر بطاقات مدى تحديداً، ومنها Apple Pay ببطاقة مدى، على الإعداد الحي وليس بيئة التجربة فقط.
- تأكد من نوع العملية والمنطقة التي يدعمها حسابك لدى البوابة قبل كتابة الكود.
- خزّن المبالغ بالهللة كأرقام صحيحة.
- لا تعتمد الدفعة بناءً على عودة التطبيق. أكّدها من السيرفر مع البوابة.
- عالج الـ Webhook والاستعلام عن الحالة معاً، واجعل الاعتماد آمناً إن تكرر.
- تحقق من مصدر كل Webhook بالطريقة التي توفرها البوابة، وقارن مقارنة ثابتة الزمن.
- طابق المبلغ والعملة عند التأكيد.
- أبقِ الخدمات الخارجية (الشحن، الرسائل) خارج معاملة الدفع، وقابلة لإعادة المحاولة.
- في التطبيق، عالج انتقاله للخلفية وانتهاء الجلسة وإغلاق العميل لصفحة الدفع.
- احسب الضريبة والإجمالي في السيرفر فقط.
الأسئلة الشائعة
ما طرق الدفع التي يحتاجها متجر إلكتروني في السعودية؟
الحد الأدنى مدى وفيزا وماستركارد، ومعها Apple Pay. كثير من المتاجر تضيف التقسيط عبر تابي أو تمارا للسلات الأكبر، وبعضها يُبقي الدفع عند الاستلام لفئات معينة. تأكد من البوابة أن كل طريقة مفعّلة على حسابك الحي.
هل يكفي الـ Webhook لتأكيد الدفع؟
الـ Webhook هو الإشارة الأساسية، لكنه قد يتأخر أو يتكرر. نحن نضيف إليه استعلاماً عن الحالة يطلقه التطبيق بعد العودة من صفحة الدفع. المساران ينتهيان في خطوة اعتماد واحدة تتجاهل الدفعة المكتملة.
لماذا يعيد N-Genius الخطأ 422 saleNotAllowed في السعودية؟
على حسابات التجار السعودية التي ربطناها، تُرفض قيمة SALE بهذا الخطأ. القيمة المدعومة للتفويض والتحصيل في خطوة واحدة هناك هي PURCHASE. تأكد من Network International لإعدادات حسابك.
هل أبني نموذج بطاقة خاصاً بي أم أستخدم صفحة دفع مستضافة؟
لأغلب الأعمال، الصفحة المستضافة هي الخيار الافتراضي الصحيح. بيانات البطاقة تذهب مباشرة إلى البوابة، ومتطلبات الامتثال عليك تبقى محدودة، ودعم مدى وApple Pay يأتي من المزود. ابنِ حقولاً خاصة فقط إن كانت لديك حاجة تصميمية واضحة وفريق يتحمل نطاق الأمان الإضافي.
كم يستغرق ربط بوابة دفع سعودية؟
استدعاءات الـ API جزء صغير من العمل. أغلب الوقت يذهب في تفعيل حساب التاجر، ومسارات التحقق، ومعالجة الـ Webhook، وحالات التطبيق الطرفية، واختبار البطاقات الحقيقية. خطط للمسار كاملاً، لا لزر "ادفع" فقط.
الخطوة التالية
إن كنت تضيف الدفع إلى منتج في السعودية، أو عندك مسار دفع يولّد تذاكر "دفعت والطلب غير مدفوع"، أرسل لنا وصف مشروعك. سنخبرك أي النقاط أعلاه تنطبق على حالتك، ويمكنك الاطلاع على طريقة تسعيرنا لهذا النوع من العمل في صفحة الخدمات.