Quick Start
أنشئ أول جلسة دفع لك في أقل من 5 دقائق
API Reference
وثائق API كاملة واختبار تفاعلي
Preview Endpoint
احسب الأسعار والضرائب قبل إنشاء الجلسة
صلاحية الجلسة: تنتهي صلاحية جلسات الدفع بعد 24 ساعة افتراضيًا، أو بعد 15 دقيقة عند
confirm: true.المتطلبات الأساسية
تحتاج إلى:- حساب تاجر نشط في Dodo Payments
- بيانات اعتماد API من Developer → API Keys في لوحة التحكم
- منتج واحد على الأقل تم إنشاؤه في Products
إنشاء أول جلسة دفع لك
- Node.js SDK
- Python SDK
- REST API
استجابة API
تعيد جميع الطرق ما يلي:session_id فقط. عند توفير payment_method_id، تتم معالجة الرسوم فورًا ويكون checkout_url هو null. استخدم payment_id المُعاد بدلًا منه.
عند confirm: true، يتم إنشاء الدفع في وقت إنشاء الجلسة، وتتضمن الاستجابة أيضًا payment_id وclient_secret وpublishable_key لاستخدامها مع Dodo Payments checkout SDK.
إعادة توجيه عميلك
1
Extract the checkout URL
احصل على
checkout_url من استجابة API.2
Redirect to checkout
أرسل عميلك إلى عنوان URL التالي:بدلًا من ذلك، افتحه في نافذة جديدة:
3
Handle the return
بعد الدفع، تتم إعادة توجيه العملاء إلى
return_url مع معلمات الاستعلام التالية:مثال على إعادة التوجيه:
التحقق من حالة الجلسة
للتحقق من حالة الجلسة، استدعِ Get Checkout Session (GET /checkouts/{id}). يتضمن الرد id وcreated_at وcustomer_email وcustomer_name الخاصة بالجلسة، بالإضافة إلى payment_id وpayment_status. تكون حقولا الدفع كلاهما null ما دام العميل لا يزال يُدخل بياناته. بعد أن يرسل العميل بيانات الدفع، يحتفظ payment_status بحالة الدفع، مثل succeeded أو failed أو processing. استخدم webhooks كمصدر الحقيقة لتنفيذ الطلبات.
نص الطلب
الحقول المطلوبة
array
مطلوب
مصفوفة المنتجات المطلوب تضمينها في جلسة الدفع. يجب أن يتضمن كل منتج
product_id صالحًا من لوحة التحكم لديك.يمكنك الجمع بين منتجات الدفع لمرة واحدة ومنتج اشتراك واحد في الجلسة نفسها. ويمكن أن تحتوي سلة التسوق أيضًا على منتجي اشتراك أو أكثر، لكنها عندئذٍ لا يمكن أن تحتوي على منتجات لمرة واحدة. راجع سلة الاشتراكات المتعددة. تحتوي السلة على 20 منتجًا كحد أقصى.الحقول الاختيارية
Customer Information
Customer Information
object
معلومات العميل. يمكنك إرفاق عميل موجود باستخدام معرّفه، أو إنشاء سجل عميل جديد أثناء الدفع.
- Attach Existing Customer
- Create New Customer
object
معلومات عنوان الفوترة لحساب الضرائب بدقة ومنع الاحتيال والامتثال للمتطلبات التنظيمية.عند
confirm: true، تصبح جميع حقول عنوان الفوترة مطلوبة، ما لم تكن minimal_address هي true.Payment Configuration
Payment Configuration
array
تحكّم في طرق الدفع المتاحة للعملاء أثناء الدفع. يساعد ذلك على تحسين التجربة لأسواق أو متطلبات تجارية محددة.الخيارات الشائعة:
credit، debit، upi_collect، apple_pay، google_pay، amazon_pay، klarna، affirm، afterpay_clearpay، cashapp، ach، multibanco، bancontact_card، eps، ideal، blik، gcash، ali_pay_hk، fps، touch_n_go، paypalراجع مرجع Create Checkout Session API للاطلاع على القائمة الكاملة.مثال:string
تجاوز اختيار العملة الافتراضي باستخدام عملة فوترة ثابتة. يستخدم رموز العملات وفق ISO 4217.العملات المدعومة:
USD، EUR، GBP، CAD، AUD، INR، وغير ذلكمثال: "USD" للدولار الأمريكي، و"EUR" لليورولا يكون هذا الحقل فعالًا إلا عند تفعيل التسعير التكيفي. إذا كان التسعير التكيفي معطلًا، تتجاهل API هذا الحقل، وتُستمد العملة من سعر المنتج أو بلد الفوترة.boolean
افتراضي:"false"
اعرض طرق الدفع المحفوظة مسبقًا للعملاء العائدين لتحسين سرعة الدفع وتجربة المستخدم.
Session Management
Session Management
string
عنوان URL لإعادة توجيه العملاء بعد اكتمال الدفع. يضيف Dodo Payments معلمات استعلام إلى عنوان URL عند إعادة التوجيه (راجع جدول إعادة التوجيه أعلاه).أمثلة على عناوين URL لإعادة التوجيه:استخدم معلمتي الاستعلام
license_key وemail لعرض مفاتيح الترخيص أو إرسال تأكيد فورًا في صفحة العودة، دون الحاجة إلى استدعاء API إضافي.string
عنوان URL لإعادة توجيه العملاء عند النقر على زر الرجوع أو إلغاء جلسة الدفع. إذا لم يُوفَّر، فلن يظهر زر الرجوع.عيّن
cancel_url لتوفير طريقة واضحة للعملاء للعودة إلى موقعك دون إتمام عملية الشراء.boolean
افتراضي:"false"
إذا كانت القيمة true، تُنهي جميع تفاصيل الجلسة فورًا. تعرض API خطأً عند فقدان بيانات مطلوبة.عند
confirm: true:- تصبح جميع حقول عنوان الفوترة مطلوبة (فقط
countryوzipcodeعندما تكونminimal_addressهيtrue) - يمكن توفير
payment_method_idلمعالجة الرسوم فورًا - تنتهي صلاحية الجلسة بعد 15 دقيقة بدلًا من 24 ساعة
- يلزم وجود
customer_idإذا تم توفيرpayment_method_id
array
طبّق رمز خصم واحدًا أو أكثر بشكل متتابع على جلسة الدفع. تُطبّق الرموز بترتيب المصفوفة (يخفض الرمز الأول السعر الابتدائي، والثاني السعر بعد الخصم الأول، وهكذا)، بحد أقصى 20 رمزًا لكل جلسة.عند تفعيل Purchasing Power Parity، يكون السعر الابتدائي هو المبلغ المعدّل وفق PPP، وليس السعر الأساسي.الحقل المفرد
discount_code أدناه مهمل لكنه لا يزال مدعومًا بالكامل. لا يمكن دمجه مع discount_codes في الطلب نفسه.string
مهمل
مهمل — يُفضّل استخدام
discount_codes للتكاملات الجديدة. لا يزال هذا الحقل يعمل للتوافق مع الإصدارات السابقة، لكنه لا يمكن دمجه مع discount_codes في الطلب نفسه.object
أزواج مخصصة من المفتاح والقيمة لتخزين معلومات إضافية حول الجلسة.
boolean
تجاوز سلوك 3DS الافتراضي للتاجر لهذه الجلسة.
boolean
افتراضي:"false"
فعّل وضع جمع الحد الأدنى من العنوان. عند تفعيله، يجمع الدفع:
- البلد: مطلوب دائمًا لتحديد الضرائب
- الرمز البريدي/ZIP: في المناطق التي يلزم فيها لحساب ضريبة المبيعات أو VAT أو GST فقط
confirm: true، لا يلزم سوى zipcode (بالإضافة إلى country)؛ وتظل حقول عنوان الفوترة الأخرى اختيارية.string
وسيلة دفع محفوظة تخص العميل المرتبط. تتطلب
confirm: true وcustomer.customer_id موجودًا. يتم التحقق من أهلية وسيلة الدفع باستخدام عملة الدفعة. عند تعيينها، تتم معالجة الرسوم فورًا، ويُرجع checkout_url على أنه null. استخدم payment_id المُرجع بدلًا منه.boolean
افتراضي:"false"
إذا كانت القيمة true، يُرجع عنوان URL مختصرًا لإتمام الدفع بدلًا من عنوان URL الكامل للجلسة.
string
معرّف مجموعة المنتجات لتدفق إتمام الدفع القائم على المجموعات. عند تعيينه، مرّر مصفوفة
product_cart فارغة. لا يمكن تطبيق أكواد الخصم مسبقًا عند إنشاء الجلسة. راجع مجموعات المنتجات.string
المعرّف الضريبي للعميل (مثل رقم VAT). يتطلب
billing_address مع country.string
اسم تجاري أو قانوني اختياري مرتبط بالمعرّف الضريبي، بحد أقصى 250 حرفًا. عند توفيره مع
tax_id صالح، يظهر في الفاتورة بدلًا من الاسم الشخصي للعميل.integer
تجاوز الحد الأدنى للتفويض على مستوى التاجر (بوحدة paise من INR) للتفويضات الإلكترونية بعملة INR على البطاقات الهندية.المبلغ المُرسل إلى المعالج هو
max(this_floor, actual_billing_amount)، لذا يمثّل هذا فعليًا حد التفويض الظاهر للعميل عندما تكون الفوترة أقل منه. عند عدم تعيينه، يُطبّق إعداد التاجر؛ وإذا لم يكن ذلك الإعداد معينًا أيضًا، يُطبّق الإعداد الافتراضي للنظام، وهو ₹15,000.UI Customization
UI Customization
object
خصّص مظهر واجهة إتمام الدفع وسلوكها.
Feature Flags
Feature Flags
object
اضبط الميزات والسلوكيات المحددة لجلسة إتمام الدفع.
Custom Fields
Custom Fields
array
اجمع معلومات إضافية من العملاء أثناء إتمام الدفع باستخدام حقول نماذج مخصصة. يمكنك تعريف ما يصل إلى 5 حقول مخصصة لكل جلسة إتمام دفع. تُضمّن ردود العملاء في حمولات webhook وتتاح عبر API.
- Webhooks: تحتوي
payment.succeededوsubscription.activeوحمولات الأحداث الأخرى ذات الصلة على مصفوفةcustom_field_responses - استجابات API: تتضمن كائنات الدفع والاشتراك
custom_field_responses
Subscription Configuration
Subscription Configuration
object
إعداد إضافي لجلسات إتمام الدفع التي تتضمن منتجات اشتراك.
أمثلة على الاستخدام
إتمام دفع بسيط لمنتج واحد
سلة متعددة المنتجات
سلة اشتراكات متعددة
لبيع عدة منتجات اشتراك في عملية إتمام دفع واحدة، أضف منتجي اشتراك أو أكثر إلىproduct_cart. يدفع العميل مرة واحدة، وتنشئ Dodo Payments دفعة واحدة وفاتورة واحدة واشتراكًا واحدًا لكل منتج. لكل اشتراك دورة فوترة خاصة به ويتجدد بشكل مستقل، لذا يمكن لمنتج شهري ومنتج سنوي مشاركة السلة.
- لا يمكنها احتواء منتجات لمرة واحدة. ترفض API الطلب بالخطأ
422. - تحتوي على 20 منتج اشتراك كحد أقصى.
- لا يمكنها إدراج المنتج نفسه مرتين. لبيع أكثر من وحدة من منتج، عيّن
quantityبدلًا من ذلك. - لا يمكنها استخدام الفوترة عند الطلب (
subscription_data.on_demand). - يُحتسب كود الخصم المطبّق على السلة كعملية استرداد واحدة.
subscription_data.trial_period_days على كل اشتراك في السلة. بدونه، يستخدم كل اشتراك الفترة التجريبية المحددة على منتجه. عندما لا تعيّنه ويكون خيار منع إساءة استخدام الفترة التجريبية مفعّلًا، يبدأ المنتج الذي سبق للعميل تجربته من دون فترة تجريبية.
تحتوي الدفعة الناتجة على is_multi_subscription: true وتسرد كل اشتراك تبدأه في subscription_ids. وتكون قيمة subscription_id هي null، لأنه لا يوجد اشتراك واحد يملك الدفعة. يحمل webhook من نوع payment.succeeded الحقول نفسها. اقرأ is_multi_subscription لمعرفة نوع الدفع، وليس طول subscription_ids.
بعد نجاح الدفع، تتلقى حدث payment.succeeded واحدًا للسلة وحدث subscription.active واحدًا لكل اشتراك. بعد ذلك، يتجدد كل اشتراك ويغيّر خطته ويُلغى بشكل مستقل، مع فاتورته الخاصة لكل عملية تجديد.
تشترك جميع الاشتراكات من سلة واحدة في وسيلة الدفع التي استخدمها العميل عند إتمام الدفع. عند تحديث وسيلة الدفع لأحدها، تنقل Dodo Payments وسيلة الدفع الجديدة إلى كل اشتراك من السلة نفسها لديه عملة تسوية وعملة فوترة متماثلتان ويكون active أو on_hold أو past_due أو paused. يبدأ كل اشتراك من السلة بعملة التسوية وعملة الفوترة نفسيهما، حتى عندما تكون لمنتجاته عملات أسعار مختلفة. وقد يؤدي تغيير لاحق، مثل تغيير الخطة، إلى نقل الاشتراك إلى عملة تسوية أو فوترة أخرى. يحتفظ ذلك الاشتراك بوسيلة الدفع القديمة، لذا حدّثه بشكل منفصل. بالنسبة إلى اشتراك on_hold، يعيد التحديث محاولة تحصيل الفاتورة غير المدفوعة لذلك الاشتراك فقط.
اشتراك مع فترة تجريبية
إتمام دفع مؤكد مسبقًا
إتمام الدفع مع تجاوز العملة
وسائل الدفع المحفوظة للعملاء العائدين
إتمام دفع B2B مع جمع المعرّف الضريبي
إتمام الدفع بالنسق الداكن مع أكواد خصم متراصة
وسائل الدفع الإقليمية (UPI للهند)
للحصول على معلومات تفصيلية حول إعداد UPI واختباره، راجع صفحة وسائل الدفع في الهند.إتمام الدفع باستخدام BNPL (اشترِ الآن وادفع لاحقًا)
للحصول على معلومات تفصيلية حول إعداد BNPL واختباره، راجع صفحة اشترِ الآن وادفع لاحقًا (BNPL).إتمام الدفع الفوري باستخدام وسيلة دفع موجودة
روابط مختصرة لعناوين URL أوضح للدفع
تخطي صفحة نجاح الدفع مع إعادة توجيه فورية
فرض لغة محددة
جمع الحقول المخصصة
معاينة جلسات إتمام الدفع
استخدم نقطة النهاية Preview Checkout Session لحساب الأسعار والضرائب والإجماليات قبل إنشاء جلسة. يفيد ذلك في عرض معلومات أسعار دقيقة على موقعك.يعكس
current_breakup.subtotal المُعاين بالفعل تعادل القوة الشرائية والتسعير الجذاب عند انطباقهما على المنتج.عندما تحتوي السلة على منتج اشتراك، يعيد رد المعاينة أيضًا
next_billing_date — وهي معاينة لتاريخ الفوترة القادم، حتى تتمكن من عرضه قبل إنشاء الاشتراك. يُحسب هذا التاريخ نسبةً إلى الوقت الحالي: now + trial period عند انطباق فترة تجريبية، وإلا فـ now + one payment frequency. يُحذف الحقل من السلال التي تحتوي على منتجات لمرة واحدة فقط. هذا تقدير يستند إلى وقت المعاينة؛ أما next_billing_date المعتمد فيُحدد عند تفعيل الاشتراك.يعيد رد المعاينة أيضًا
trial_period_days (مدة الفترة التجريبية الفعلية، المجانية أو المدفوعة) وtrial_amount (رسوم الفترة التجريبية لكل وحدة بعد الخصومات، بوحدات الفئة الصغرى لعملة السعر). لا يظهر trial_amount إلا في فترة تجريبية مدفوعة، وتكون قيمته null في الفترة التجريبية المجانية أو عند عدم وجود فترة تجريبية. استخدم current_breakup للإجمالي الخاضع للضريبة المستحق فعليًا اليوم.بالنسبة إلى سلة الاشتراكات المتعددة، يعيد الرد أيضًا مصفوفة
subscriptions تحتوي على إدخال لكل اشتراك: product_id وamount_due_now وtax_due_now وrecurring_amount وrecurring_tax وtrial_period_days وnext_billing_date. ويكون next_billing_date على المستوى الأعلى هو التاريخ الأسبق في السلة، بينما يكون trial_period_days وtrial_amount على المستوى الأعلى بقيمة null. اقرأ المبالغ من subscriptions وcurrent_breakup. يجمع recurring_breakup مبالغ تجديد جميع الاشتراكات، حتى عندما تتجدد في تواريخ مختلفة؛ لذا اقرأ كل عملية تجديد من subscriptions.- Node.js SDK
- Python SDK
- REST API
الترحيل من Dynamic Links
إذا كنت تستخدم Dynamic Links، توفر جلسات إتمام الدفع مرونة أكبر. مع Dynamic Links، كان عليك توفير عنوان الفوترة الكامل للعميل. أما مع جلسات إتمام الدفع، فيمكنك تمرير أي معلومات متاحة لديك، ويتولى تدفق إتمام الدفع جمع الباقي. على سبيل المثال:- وفّر بلد الفوترة للعميل فقط، وستجمع عملية إتمام الدفع التفاصيل المتبقية.
- أو وفّر جميع المعلومات واضبط
confirm: trueللانتقال مباشرةً إلى صفحة الدفع.
الموارد ذات الصلة
Overlay Checkout
افتح عملية إتمام الدفع كتراكب modal في صفحتك
Inline Checkout
ضمّن عملية إتمام الدفع مباشرةً في صفحتك
Mobile Integration
ادمج عملية إتمام الدفع في تطبيقات الهاتف المحمول الأصلية
Webhooks
استمع إلى أحداث الدفع والاشتراك
Payment Methods
وسائل الدفع المدعومة حسب المنطقة
Subscriptions
الفوترة المتكررة وإدارة الاشتراكات