Skip to main content

Quick Start

أنشئ أول جلسة دفع لك في أقل من 5 دقائق

API Reference

وثائق API كاملة واختبار تفاعلي

Preview Endpoint

احسب الأسعار والضرائب قبل إنشاء الجلسة
صلاحية الجلسة: تنتهي صلاحية جلسات الدفع بعد 24 ساعة افتراضيًا، أو بعد 15 دقيقة عند confirm: true.
الروابط ذات الاستخدام الواحد: لا يمكن إعادة استخدام checkout_url. أنشئ جلسة جديدة لكل عميل ومحاولة دفع بدلًا من مشاركة الرابط أو إعادة استخدامه.

المتطلبات الأساسية

تحتاج إلى:
  • حساب تاجر نشط في Dodo Payments
  • بيانات اعتماد API من Developer → API Keys في لوحة التحكم
  • منتج واحد على الأقل تم إنشاؤه في Products

إنشاء أول جلسة دفع لك

استجابة 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 مع معلمات الاستعلام التالية:مثال على إعادة التوجيه:
بدلًا من إعادة التوجيه، يمكنك تضمين الدفع مباشرةً في صفحتك باستخدام Overlay Checkout (نافذة منبثقة)، أو Inline Checkout (مضمّن)، أو Mobile SDKs (تطبيقات أصلية). تستخدم جميعها عنوان 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 منتجًا كحد أقصى.
العثور على معرّفات المنتجات: يمكنك العثور على معرّفات المنتجات في لوحة تحكم Dodo Payments ضمن Products → View Details، أو باستخدام List Products API.

الحقول الاختيارية

object
معلومات العميل. يمكنك إرفاق عميل موجود باستخدام معرّفه، أو إنشاء سجل عميل جديد أثناء الدفع.
object
معلومات عنوان الفوترة لحساب الضرائب بدقة ومنع الاحتيال والامتثال للمتطلبات التنظيمية.عند confirm: true، تصبح جميع حقول عنوان الفوترة مطلوبة، ما لم تكن minimal_address هي true.
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 للاطلاع على القائمة الكاملة.
أدرج دائمًا credit وdebit كخيارين احتياطيين لمنع فشل الدفع عند عدم توفر طرق الدفع المفضلة.
مثال:
string
تجاوز اختيار العملة الافتراضي باستخدام عملة فوترة ثابتة. يستخدم رموز العملات وفق ISO 4217.العملات المدعومة: USD، EUR، GBP، CAD، AUD، INR، وغير ذلكمثال: "USD" للدولار الأمريكي، و"EUR" لليورولا يكون هذا الحقل فعالًا إلا عند تفعيل التسعير التكيفي. إذا كان التسعير التكيفي معطلًا، تتجاهل API هذا الحقل، وتُستمد العملة من سعر المنتج أو بلد الفوترة.
boolean
افتراضي:"false"
اعرض طرق الدفع المحفوظة مسبقًا للعملاء العائدين لتحسين سرعة الدفع وتجربة المستخدم.
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 المُرجع بدلًا منه.
إذا كانت القيمة 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.
object
خصّص مظهر واجهة إتمام الدفع وسلوكها.
object
اضبط الميزات والسلوكيات المحددة لجلسة إتمام الدفع.
array
اجمع معلومات إضافية من العملاء أثناء إتمام الدفع باستخدام حقول نماذج مخصصة. يمكنك تعريف ما يصل إلى 5 حقول مخصصة لكل جلسة إتمام دفع. تُضمّن ردود العملاء في حمولات webhook وتتاح عبر API.
تُضمّن ردود العملاء على الحقول المخصصة في:
  • Webhooks: تحتوي payment.succeeded وsubscription.active وحمولات الأحداث الأخرى ذات الصلة على مصفوفة custom_field_responses
  • استجابات API: تتضمن كائنات الدفع والاشتراك custom_field_responses
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.
إذا كنت تستخدم Dynamic Links، توفر جلسات إتمام الدفع مرونة أكبر. مع Dynamic Links، كان عليك توفير عنوان الفوترة الكامل للعميل. أما مع جلسات إتمام الدفع، فيمكنك تمرير أي معلومات متاحة لديك، ويتولى تدفق إتمام الدفع جمع الباقي. على سبيل المثال:
  • وفّر بلد الفوترة للعميل فقط، وستجمع عملية إتمام الدفع التفاصيل المتبقية.
  • أو وفّر جميع المعلومات واضبط confirm: true للانتقال مباشرةً إلى صفحة الدفع.
الترحيل بسيط: حدّث تكاملك لاستخدام API جلسات إتمام الدفع أو طريقة SDK، واضبط حمولة الطلب لتتوافق مع تنسيق جلسات إتمام الدفع، وانتهى الأمر. لا حاجة إلى معالجة إضافية.

الموارد ذات الصلة

Overlay Checkout

افتح عملية إتمام الدفع كتراكب modal في صفحتك

Inline Checkout

ضمّن عملية إتمام الدفع مباشرةً في صفحتك

Mobile Integration

ادمج عملية إتمام الدفع في تطبيقات الهاتف المحمول الأصلية

Webhooks

استمع إلى أحداث الدفع والاشتراك

Payment Methods

وسائل الدفع المدعومة حسب المنطقة

Subscriptions

الفوترة المتكررة وإدارة الاشتراكات
آخر تعديل في ٨ أكتوبر ٢٠٢٦