ربط API بوابة الدفع مع طويق باي: دليل المطورين وأصحاب المتاجر
ربط API بوابة الدفع هو اتصال متجرك أو تطبيقك ببوابة الدفع برمجيًا، لإرسال بيانات الطلب واستقبال نتيجة الدفع تلقائيًا دون تدخل يدوي. وتقدم طويق باي هذا الربط عبر واجهة REST API موثقة، مع Webhooks وبيئة اختبار Sandbox وفريق دعم فني للمطورين، لتبني تجربة دفع متكاملة داخل منتجك.
يمكنك أيضاً زيارة الموقع الرسمي لطويق باي، أو التواصل عبر واتساب، أو تحميل التطبيق من Google Play أو App Store.
الخلاصة السريعة
- ما هو؟ ربط API بوابة الدفع يتيح قبول المدفوعات داخل موقعك أو تطبيقك مباشرة.
- كيف تبدأ مع طويق باي؟ اطلب صلاحية الوصول من الفريق، واختبر في Sandbox، ثم انطلق إلى التشغيل الفعلي.
- ماذا تحصل عليه؟ واجهة REST وتوثيق وWebhooks ومفاتيح API ودعم فني للمطورين.
- ما الأمان؟ توافق مع PCI DSS، ودعم Tokenization و3D Secure.
- ما التكلفة؟ لا رسوم تأسيس ولا اشتراك شهري ولا رسوم مخفية.
ما المقصود بربط API بوابة الدفع؟
بوابة الدفع هي الوسيط الذي يربط متجرك بالعميل والبنك. وعند ربط API بوابة الدفع يرسل نظامك طلبًا برمجيًا بالمبلغ وتفاصيل الطلب، ثم يستقبل حالة العملية ويحدّث الطلب تلقائيًا. بعد ذلك تتم التسوية وتحويل المستحقات إلى حسابك البنكي.
والنتيجة أن العميل يُكمل الدفع داخل تجربة الشراء نفسها، وأن فريقك لا يتابع كل عملية يدويًا.
لماذا تختار طويق باي لربط API بوابة الدفع؟
طويق باي منصة دفع سعودية تجمع في مكان واحد ما يحتاجه فريق التطوير وصاحب النشاط:
- واجهة REST واضحة: نقاط نهاية بسيطة تتبع معايير REST، فيسهل على أي مطور فهمها.
- بيئة Sandbox: تختبر تكاملك بأمان قبل أول عملية حقيقية.
- Webhooks: إشعارات فورية بنتيجة كل عملية.
- دعم فني للمطورين: فريق تقني يساعد أثناء التطوير.
- وسائل دفع متنوعة: Apple Pay ومدى وMastercard وVisa وAmerican Express.
- لا رسوم تأسيس ولا اشتراك شهري: تدفع فقط على العمليات الناجحة.
- أدوات إضافية في حساب واحد: روابط الدفع ورمز QR وحسابات فرعية، فتبدأ بما يناسبك ثم تتوسع.
متى تحتاج ربط API بوابة الدفع؟
لا يحتاج كل نشاط إلى ربط تقني. اختر حسب طبيعة عملك:
| الحالة | الأنسب |
|---|---|
| تبيع عبر واتساب أو إنستغرام أو تقدم خدمات | روابط الدفع أو رمز QR دون مبرمج |
| متجر إلكتروني تريد الدفع داخله مباشرة | ربط API بوابة الدفع |
| تطبيق أو منصة SaaS بنظام طلبات خاص | ربط API بوابة الدفع |
| تريد البدء سريعًا ثم التوسع | ابدأ بروابط الدفع ثم أضف الربط التقني |
وللمقارنة بين طرق الربط راجع ربط بوابة الدفع بالمتجر الإلكتروني: 5 طرق لاختيار الأنسب.
ماذا تقدم واجهة طويق باي للمطورين؟
| العنصر | ما يعنيه لفريقك |
|---|---|
| واجهة RESTful | نقاط نهاية واضحة تتبع معايير REST |
| توثيق | أدلة تفصيلية ومرجع لكل نقطة نهاية |
| Webhooks | إشعارات فورية عند حدوث أي عملية |
| بيئة Sandbox | اختبار التكامل بأمان قبل التشغيل الفعلي |
| مفاتيح API | طلبات موثّقة بمفاتيح تتحكم بها بالكامل |
| دعم فني للمطورين | فريق تقني يساعد أثناء التطوير |
خطوات ربط API بوابة الدفع مع طويق باي
الخطوة الأولى: اطلب صلاحية الوصول
تواصل مع فريق طويق باي للحصول على مفاتيح API الخاصة بك. يمكنك البدء عبر التواصل من خلال واتساب
الخطوة الثانية: اختبر في بيئة Sandbox
ابنِ تكاملك واختبره في بيئة آمنة لا تتضمن عمليات حقيقية. اختبر حالات النجاح والفشل، واستقبال إشعارات Webhooks، وتحديث حالة الطلب في نظامك.
الخطوة الثالثة: انطلق فعليًا
بعد اكتمال الاختبار، انتقل إلى بيئة التشغيل وابدأ معالجة المدفوعات الحقيقية. وقبل أول عملية فعلية تأكد من أن إعدادات نظامك لم تعد على وضع الاختبار، فهذا من أكثر أخطاء الإطلاق شيوعًا.
مثال توضيحي على طلب دفع
تعرض صفحة طويق باي الرسمية المثال التالي للتوضيح فقط، وتؤكد أن التفاصيل الكاملة والمفاتيح تأتي من الفريق:
curl -X POST https://api.tuwaiqpay.com.sa/v1/payments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"currency": "SAR",
"description": "Order #123"
}'
يُوثَّق الطلب بمفتاح API في ترويسة Authorization. فلا تضع المفتاح في كود الواجهة الأمامية، ولا تشاركه في مستودعات عامة.
دور Webhooks في ربط API بوابة الدفع
لا يكفي إرسال طلب الدفع. فنظامك يحتاج أن يعرف متى نجحت العملية أو فشلت، وهذا دور Webhooks: إشعارات فورية تصل خادمك عند حدوث أي عملية. وبناءً عليها تحدّث حالة الطلب، أو تفعّل الخدمة، أو ترسل تأكيدًا للعميل.
ومن الممارسات الجيدة أن تتحقق من صحة كل إشعار قبل اعتماده، وأن تتعامل مع الإشعار المكرر دون تكرار الإجراء.
الأمان في ربط API بوابة الدفع
تعتمد الواجهة على طلبات موثّقة بمفاتيح API، وتتوافق طويق باي مع معايير PCI DSS، وتدعم Tokenization و3D Secure:
| الآلية | الفائدة |
|---|---|
| PCI DSS | حماية بيانات البطاقات وفق معيار معتمد عالميًا |
| Tokenization | استبدال بيانات البطاقة برمز، فلا تُخزَّن بيانات حساسة في نظامك |
| 3D Secure | مصادقة إضافية تقلل الاحتيال في الدفع عبر الإنترنت |
المنصات التي يمكن ربطها
يمكن ربط المتاجر المبنية على Shopify وWooCommerce وWordPress من خلال API. وتدعم طويق باي منصات SaaS.
وسائل الدفع والاسترجاع والتسوية
بعد الربط يدفع عملاؤك عبر Apple Pay ومدى وMastercard وVisa وAmerican Express. وتُقبل البطاقات الدولية بشرط تفعيلها للمدفوعات عبر الإنترنت من البنك المصدر. ويتوفر استرجاع كامل أو جزئي للمبلغ حسب العملية.
وتستغرق التسوية عادة من يوم إلى 5 أيام، وغالبًا نحو 24 ساعة لعمليات Visa وMastercard، ونحو 48 ساعة لمدى.
الرسوم والتسجيل
لا توجد رسوم تأسيس أو اشتراك شهري أو رسوم مخفية. وتُحتسب الرسوم على العمليات الناجحة فقط حسب شبكة البطاقة، مع إضافة ضريبة القيمة المضافة. وللمقارنة راجع رسوم بوابات الدفع في السعودية 2026.
ويتم التسجيل عبر التطبيق: تنزيل التطبيق وإنشاء الحساب، ثم إدخال بيانات النشاط ورفع المستندات، ومراجعة الطلب، وتوقيع العقد. ويمكن تفعيل الحساب خلال 24 ساعة بعد اكتمال المتطلبات.
نصائح قبل ربط API بوابة الدفع
- حدد نوع نشاطك: متجر أم تطبيق أم منصة، وهل هو سوق متعدد البائعين.
- أشرك المطور من البداية لتقدير الوقت المطلوب.
- ابدأ بروابط الدفع إن أردت التحصيل أثناء تجهيز الربط.
- اختبر الدفع الفاشل والمرفوض، لا الناجح فقط.
- راجع 7 أسئلة يجب أن تسألها قبل التعاقد مع أي بوابة دفع.
الأسئلة الشائعة
ما المقصود بربط API بوابة الدفع؟
هو اتصال نظامك ببوابة الدفع برمجيًا لإرسال بيانات الطلب واستقبال نتيجة الدفع تلقائيًا.
كيف أحصل على مفاتيح API من طويق باي؟
تتواصل مع فريق طويق باي لطلب صلاحية الوصول، ثم تحصل على المفاتيح والتوثيق.
هل توجد بيئة اختبار؟
نعم، تتوفر بيئة Sandbox لاختبار التكامل بأمان قبل الانتقال إلى التشغيل الفعلي.
هل أحتاج مطورًا لربط API بوابة الدفع؟
نعم، يحتاج الربط عبر API إلى تنفيذ تقني. أما روابط الدفع ورمز QR فلا تحتاجان إلى مبرمج.
هل تدعم طويق باي Webhooks؟
نعم، تصلك إشعارات فورية عند حدوث أي عملية.
هل يدعم الربط Shopify وWooCommerce وWordPress؟
نعم، من خلال API.
هل هناك دعم فني للمطورين؟
نعم، يتوفر فريق تقني لمساعدتك أثناء التطوير.
هل توجد رسوم تأسيس أو اشتراك شهري؟
لا، لا توجد رسوم تأسيس أو اشتراك شهري أو رسوم مخفية.
ابدأ ربط API بوابة الدفع مع طويق باي
إذا كان متجرك أو تطبيقك جاهزًا للدفع المتكامل، فاطلب مفاتيح الوصول، واختبر التكامل في Sandbox، ثم انطلق إلى التشغيل الفعلي. يمكنك أيضاً زيارة الموقع الرسمي لطويق باي، أو التواصل عبر واتساب، أو تحميل التطبيق من Google Play أو App Store.
