
Checkout Sessions API
Preview Checkout
Payment Methods
Integration Guide
روابط الدفع التي يتم إنشاؤها عبر Checkout Sessions API غير قابلة لإعادة الاستخدام. تنتهي صلاحيتها بعد 24 ساعة، أو بعد 15 دقيقة إذا تم تعيين
confirm: true. أنشئ جلسة جديدة لكل عميل ولكل محاولة دفع.Adaptive Currency
تتيح Adaptive Currency للعملاء الدفع بعملتهم المحلية المفضلة، مما يحسّن الثقة ومعدلات التحويل. عند تفعيلها، يرى العملاء محددًا للعملة في صفحة الدفع. يتحول السعر إلى العملة التي يختارونها وفق أسعار الصرف الأجنبي المباشرة. إذا تم تفعيل Purchasing Power Parity للمنتج، يتحول السعر المعدّل وفق PPP بدلًا من السعر الأساسي. وإذا تم تفعيل Charm Pricing، يُقرّب المبلغ المحوّل إلى نهاية ملائمة مثل 49.99.
Adaptive Currency
الدفع متعدد اللغات
يدعم الدفع 22 لغة. ويمكن للعملاء تبديل اللغة مباشرةً من الصفحة، كما تتم ترجمة نصوص واجهة المستخدم والتسميات ورسائل النظام. في اللغتين العربية والعبرية، يتم عرض صفحة الدفع من اليمين إلى اليسار وينعكس التخطيط بالكامل. تحافظ عناوين البريد الإلكتروني والرموز وأرقام الهواتف على ترتيب القراءة الطبيعي لها.
اللغات المدعومة
لفرض استخدام لغة محددة، عيّن
customization.force_language عند إنشاء جلسة دفع. راجع Checkout Sessions API لمزيد من التفاصيل.
الحساب التلقائي للضرائب
يتم حساب الضرائب تلقائيًا استنادًا إلى موقع إصدار فواتير العميل، بما يضمن الامتثال لمتطلبات GST وVAT وضريبة المبيعات. تُطبَّق القواعد الضريبية استنادًا إلى بلد العميل ومنطقته، حيثما ينطبق ذلك. يتم تحديث مبلغ الضريبة تلقائيًا عندما يغيّر العميل بلده أو يحدّث عنوانه. ويُعرض التفصيل النهائي للضريبة بوضوح قبل الدفع.دعم المعرّف الضريبي للنشاط التجاري
بالنسبة إلى معاملات B2B، تتيح صفحة الدفع للعملاء إدخال المعرّف الضريبي لنشاطهم التجاري (مثل رقم VAT أو GST). عند إدخاله، يتم التحقق من المعرّف الضريبي في الوقت الفعلي، وتُطبَّق تلقائيًا الإعفاءات الضريبية أو قواعد الاحتساب العكسي المنطبقة.
رموز الخصم
يمكن للعملاء تطبيق رموز الخصم أو الرموز الترويجية التي أنشأتها في لوحة التحكم. يتم التحقق من الخصم فورًا ويُعرض السعر المحدّث. عند تمكين Purchasing Power Parity على منتج، يُطبَّق الخصم على السعر المعدّل وفق PPP، وليس على السعر الأساسي.
يقبل
discount_codes مصفوفة تحتوي على ما يصل إلى 20 رمزًا، ويتم تطبيقها بالتسلسل. أما الحقل المفرد discount_code فهو مهمل، لكنه لا يزال يعمل لضمان التوافق مع الإصدارات السابقة.Discount Codes
Validate Discount by Code
جمع العناوين الذكي
تدعم صفحة الدفع إدخال العنوان بمرونة لتحقيق التوازن بين السرعة والدقة والتغطية العالمية.الخيارات
وضع العنوان المختصر
لتحقيق أعلى معدل تحويل، فعّل جمع العنوان المختصر لتقليل الاحتكاك أثناء الدفع. عند تعيينminimal_address إلى true، تجمع صفحة الدفع البيانات التالية فقط:
- البلد — مطلوب دائمًا لتحديد الضرائب
- الرمز البريدي — في المناطق التي يكون فيها ضروريًا فقط لحساب ضريبة المبيعات أو VAT أو GST

يكون جمع العنوان الكامل مفعّلًا افتراضيًا. فعّل
minimal_address للمنتجات الرقمية وتدفقات SaaS التي لا تتطلب تفاصيل فوترة كاملة.جمع أرقام الهواتف
تحكم في ظهور حقل رقم الهاتف في صفحة الدفع وما إذا كان مطلوبًا.الحقول المخصصة
اجمع معلومات إضافية من العملاء أثناء الدفع من خلال تحديد حقول نموذج مخصصة. يفيد ذلك في جمع اسم الشركة أو حجم الفريق أو مصدر الإحالة أو أي بيانات أخرى خاصة بالنشاط التجاري.أنواع الحقول المتاحة
مثال
تُضمَّن استجابات العملاء تلقائيًا في حمولات webhook (
payment.succeeded وsubscription.active) وفي استجابات API من خلال مصفوفة custom_field_responses. يمكنك تحديد ما يصل إلى 5 حقول مخصصة لكل جلسة دفع.Custom Fields Guide
قبول سياسة الخصوصية والشروط
لضمان الشفافية القانونية والامتثال:- يتم عرض رابطَي سياسة الخصوصية وشروط المشتري بوضوح في صفحة الدفع
- يقرّ العملاء بهذين المستندين صراحةً قبل إتمام الدفع
يساعد ذلك في استيفاء متطلبات حماية المستهلك وخصوصية البيانات عالميًا، بما في ذلك الامتثال للائحة GDPR.
مجموعات المنتجات
تتيح مجموعات المنتجات تجربة دفع موحّدة، حيث يمكن للعملاء عرض منتجات متعددة ذات صلة واختيارها (مثل خطط Starter وPro وEnterprise) ضمن عملية دفع واحدة. عند استخدام مجموعة، يتم عرض جميع المنتجات النشطة فيها. ويتم تحديد المنتج الأول مسبقًا، ويمكن للعملاء مقارنة الخيارات قبل الاختيار.Product Collections
إعداد جلسة الدفع
تحكم في سلوك صفحة الدفع باستخدام Checkout Sessions API:بعد الدفع، تتم إعادة توجيه العملاء إلى
return_url مع إلحاق معلمات الاستعلام تلقائيًا، بما في ذلك payment_id أو subscription_id، وstatus، وemail، وlicense_key (إن أمكن). راجع دليل Checkout Sessions للاطلاع على القائمة الكاملة.Checkout Sessions API
Checkout Integration Guide
تخصيص السمة
خصّص مظهر صفحة الدفع ليتوافق مع علامتك التجارية باستخدام المعلمةcustomization.theme_config. اضبط الألوان والخطوط ونصف قطر الحدود ونص الزر لكل من الوضعين الفاتح والداكن.
يغطي هذا القسم API من جهة الخادم، الذي يستخدم أسماء خصائص مثل bg_primary. تنطبق السمة المحددة في الجلسة على صفحات الدفع المستضافة وoverlay وinline. أما خيار themeConfig من جهة العميل في Checkout SDK، والذي يستخدم أسماء خصائص مثل bgPrimary، فهو مهمل. راجع Overlay Checkout.

Design & Theme Customization
خيارات إعداد السمة
إعداد الألوان (الوضع الفاتح/الداكن)
يدعم كل وضع خصائص الألوان التالية:تقبل جميع حقول الألوان تنسيقات ألوان CSS القياسية:
- Hex:
#fffو#ffffffو#ffffffff - RGB/RGBA:
rgb(255, 255, 255)وrgba(255, 255, 255, 0.5) - HSL/HSLA:
hsl(120, 100%, 50%)وhsla(120, 100%, 50%, 0.5) - الألوان المسماة:
redوblueوtransparent