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 صالحًا من لوحة التحكم لديك.يمكنك الجمع بين منتجات الدفع لمرة واحدة ومنتجات الاشتراك في الجلسة نفسها.الحقول الاختيارية
Customer Information
Customer Information
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" لليورولا يكون هذا الحقل فعالًا إلا عند تفعيل التسعير التكيفي. عند تعطيل التسعير التكيفي، تُستخدم العملة الافتراضية للمنتج.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:- تصبح جميع حقول عنوان الفوترة مطلوبة
- يمكن توفير
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 فقط
string
طريقة دفع محفوظة تخص العميل المرفق. تتطلب
confirm: true وcustomer.customer_id موجودًا. يتم التحقق من أهلية طريقة الدفع باستخدام عملة الدفع. عند تعيينها، تُعالج الرسوم فورًا ويُعاد checkout_url كـ null. استخدم payment_id المُعاد بدلًا من ذلك.boolean
افتراضي:"false"
إذا كانت القيمة true، يعيد عنوان URL مختصرًا للدفع بدلًا من عنوان URL الكامل للجلسة.
string
معرّف مجموعة المنتجات لتدفق الدفع القائم على المجموعات. عند تعيينه، مرّر مصفوفة
product_cart فارغة. لا يمكن تطبيق رموز الخصم مسبقًا عند إنشاء الجلسة. راجع Product Collections.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
إعدادات إضافية لجلسات الدفع التي تتضمن منتجات اشتراك.
أمثلة على الاستخدام
دفع بسيط لمنتج واحد
سلة متعددة المنتجات
اشتراك مع فترة تجريبية
دفع مؤكد مسبقًا
الدفع مع تجاوز العملة
طرق الدفع المحفوظة للعملاء العائدين
دفع B2B مع جمع Tax ID
دفع بالسمة الداكنة مع رموز خصم متتابعة
طرق الدفع الإقليمية (UPI للهند)
للحصول على معلومات تفصيلية حول إعداد UPI واختباره، راجع صفحة India Payment Methods.الدفع الآجل BNPL (اشترِ الآن وادفع لاحقًا)
للحصول على معلومات تفصيلية حول إعداد BNPL واختباره، راجع صفحة Buy Now Pay Later (BNPL).دفع فوري باستخدام طريقة دفع موجودة
روابط مختصرة لعناوين URL أوضح للدفع
تخطي صفحة نجاح الدفع مع إعادة التوجيه الفورية
فرض لغة محددة
جمع الحقول المخصصة
معاينة جلسات الدفع
استخدم نقطة النهاية Preview Checkout Session لحساب الأسعار والضرائب والإجماليات قبل إنشاء جلسة. يفيد ذلك في عرض معلومات أسعار دقيقة على موقعك.يعكس
current_breakup.subtotal الذي تمت معاينته بالفعل Purchasing Power Parity وCharm Pricing عند انطباقهما على المنتج.عندما تحتوي السلة على منتج اشتراك، يعيد رد المعاينة أيضًا
next_billing_date — وهي معاينة لتاريخ الفوترة القادم، حتى تتمكن من عرضه قبل إنشاء الاشتراك. يُحسب بالنسبة إلى الوقت الحالي: now + trial period عند انطباق تجربة، وإلا now + one payment frequency. يُحذف الحقل من السلال التي تحتوي على منتجات لمرة واحدة فقط. هذا تقدير يعتمد على وقت المعاينة؛ ويُعيّن next_billing_date المعتمد عند تفعيل الاشتراك.تعيد المعاينة أيضًا
trial_period_days (مدة التجربة الفعلية، المجانية أو المدفوعة) وtrial_amount (رسوم التجربة لكل وحدة بعد الخصومات، بوحدات العملة الفرعية). لا يظهر trial_amount إلا في تجربة مدفوعة، ويكون null في التجربة المجانية أو عند عدم وجود تجربة. استخدم current_breakup للإجمالي الخاضع للضريبة المستحق اليوم فعليًا.- Node.js SDK
- Python SDK
- REST API
الترحيل من Dynamic Links
إذا كنت تستخدم Dynamic Links، توفر Checkout Sessions مرونة أكبر. مع Dynamic Links، كان عليك توفير عنوان الفوترة الكامل للعميل. أما مع Checkout Sessions، فيمكنك تمرير أي معلومات متاحة لديك، ويجمع تدفق الدفع الباقي. على سبيل المثال:- وفّر بلد فوترة العميل فقط، وسيجمع الدفع التفاصيل المتبقية.
- أو وفّر جميع المعلومات وعيّن
confirm: trueللانتقال مباشرة إلى صفحة الدفع.
الموارد ذات الصلة
Overlay Checkout
افتح الدفع كتراكب modal في صفحتك
Inline Checkout
ضمّن الدفع مباشرةً في صفحتك
Mobile Integration
ادمج الدفع في تطبيقات الهاتف المحمول الأصلية
Webhooks
استمع إلى أحداث الدفع والاشتراك
Payment Methods
طرق الدفع المدعومة حسب المنطقة
Subscriptions
الفوترة المتكررة وإدارة الاشتراكات