Skip to main content

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

لدمج واجهة برمجة تطبيقات Dodo Payments، ستحتاج إلى:
  • حساب تاجر على Dodo Payments
  • بيانات اعتماد API (مفتاح API ومفتاح سر webhook) من لوحة التحكم

إعداد لوحة التحكم

  1. انتقل إلى لوحة تحكم Dodo Payments
  2. أنشئ منتجًا (دفعة لمرة واحدة أو اشتراك). يجب ألا يقل سعر منتجات الاشتراك عن $1 (أو ما يعادله بالعملة التي اخترتها)؛ ولا تُدعم المبالغ الأقل من هذا الحد الأدنى.
  3. أنشئ مفتاح API الخاص بك:
    • انتقل إلى المطوّر > API
    • دليل تفصيلي
    • انسخ مفتاح API الموجود في البيئة المسماة DODO_PAYMENTS_API_KEY
  4. اضبط webhooks:
    • انتقل إلى Developer > Webhooks
    • أنشئ عنوان URL لـ webhook لإشعارات الدفع
    • انسخ مفتاح webhook السري إلى البيئة

التكامل

اختر مسار التكامل الذي يناسب حالة استخدامك:
  • Checkout Sessions (موصى به): الأفضل لمعظم عمليات التكامل. أنشئ جلسة على خادمك وأعد توجيه العملاء إلى صفحة دفع آمنة ومستضافة.
  • Overlay Checkout: استخدمه عندما تحتاج إلى تجربة داخل الصفحة تفتح صفحة الدفع كتراكب مشروط على موقعك.
  • Inline Checkout: ضمّن صفحة الدفع مباشرةً في تخطيط صفحتك للحصول على تجربة دفع متكاملة تحمل علامتك التجارية.
  • Static Payment Links: عناوين URL قابلة للمشاركة فورًا وبدون تعليمات برمجية لتحصيل المدفوعات بسرعة.
  • Dynamic Payment Links: روابط يتم إنشاؤها برمجيًا. ومع ذلك، يُوصى باستخدام Checkout Sessions لأنها توفر مرونة أكبر.
  • Mobile Checkout SDKs: لتطبيقات Android وiOS وReact Native وFlutter الأصلية. أنشئ الجلسة على خادمك كما سبق، ثم مرّر checkout_url إلى SDK.
إن Overlay وInline Checkout متاحان للمتصفح فقط — إذ إنهما يضمّنان صفحة الدفع في صفحة ويب. إذا كنت تنشئ تطبيقًا أصليًا للأجهزة المحمولة، فأنشئ جلسة الدفع على خادمك وافتحها باستخدام Mobile Checkout SDKs بدلًا من ذلك.

1. Checkout Sessions

استخدم Checkout Sessions لإنشاء تجربة دفع آمنة ومستضافة للدفعات لمرة واحدة أو الاشتراكات. أنشئ جلسة على خادمك، ثم أعد توجيه العميل إلى checkout_url المُعاد.
تكون جلسات الدفع صالحة لمدة 24 ساعة افتراضيًا. إذا مرّرت confirm=true، فستكون الجلسات صالحة لمدة 15 دقيقة ويجب توفير جميع الحقول المطلوبة.
1

Create a checkout session

اختر SDK المفضل لديك أو استدعِ REST API.
2

Redirect customer to checkout

بعد إنشاء الجلسة، أعد التوجيه إلى checkout_url لبدء التدفق المستضاف.
فضّل Checkout Sessions باعتبارها الطريقة الأسرع والأكثر موثوقية لبدء قبول المدفوعات. للتخصيص المتقدم، راجع دليل Checkout Sessions الكامل ومرجع API.

2. Overlay Checkout

لتوفير تجربة دفع سلسة داخل الصفحة، استكشف تكامل Overlay Checkout الذي يتيح للعملاء إتمام المدفوعات دون مغادرة موقعك.

3. Inline Checkout

لتوفير تجارب دفع متكاملة مضمّنة مباشرةً في صفحتك، استخدم تكامل Inline Checkout. يتيح لك ذلك إنشاء ملخصات طلبات مخصصة والتحكم الكامل في تخطيط صفحة الدفع، بينما تتولى Dodo Payments تحصيل المدفوعات بأمان. تتيح لك روابط الدفع الثابتة قبول المدفوعات بسرعة عبر مشاركة عنوان URL بسيط. يمكنك تخصيص تجربة الدفع بتمرير query parameters لملء تفاصيل العميل مسبقًا، والتحكم في حقول النموذج، وإضافة بيانات وصفية مخصصة.
1

Construct your payment link

ابدأ بعنوان URL الأساسي وألحق به معرّف منتجك:
2

Add core parameters

أدرج query parameters الأساسية:
  • integer
    افتراضي:"1"
    عدد العناصر المطلوب شراؤها.
  • string
    مطلوب
    عنوان URL لإعادة التوجيه بعد اكتمال الدفع.
سيتضمن عنوان URL لإعادة التوجيه تفاصيل الدفع بوصفها query parameters، مثل:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com

إذا كانت مفاتيح الترخيص مفعّلة للمنتج، فسيُضاف أيضًا parameter باسم license_key (تُفصل المفاتيح المتعددة بفواصل):
https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
3

Pre-fill customer information (optional)

أضف حقول العميل أو الفوترة كـ query parameters لتبسيط عملية الدفع.
  • string
    الاسم الكامل للعميل (يُتجاهل إذا تم توفير firstName أو lastName).
  • string
    الاسم الأول للعميل.
  • string
    اسم عائلة العميل.
  • string
    عنوان البريد الإلكتروني للعميل.
  • string
    بلد العميل.
  • string
    عنوان الشارع.
  • string
    المدينة.
  • string
    الولاية أو المقاطعة.
  • string
    الرمز البريدي/ZIP.
  • boolean
    true أو false
4

Control form fields (optional)

يمكنك تعطيل حقول محددة لجعلها للقراءة فقط بالنسبة إلى العميل. يفيد ذلك عندما تكون لديك تفاصيل العميل مسبقًا، مثل المستخدمين الذين سجّلوا الدخول.
لتعطيل حقل، وفّر قيمته واضبط العلامة disable… المقابلة على true:
يساعد تعطيل الحقول على منع التغييرات غير المقصودة وضمان اتساق البيانات.
يؤدي ضبط showDiscounts=false إلى تعطيل قسم الخصومات وإخفائه في نموذج الدفع. استخدم ذلك إذا أردت منع العملاء من إدخال رموز القسائم أو الرموز الترويجية أثناء الدفع.
5

Add advanced controls (optional)

  • string
    يحدد عملة الدفع. تكون العملة الافتراضية هي عملة بلد الفوترة.
  • boolean
    افتراضي:"true"
    إظهار محدد العملة أو إخفاؤه.
  • number
    يحدد المبلغ المُحصَّل بوحدات العملة الرئيسية (مثلًا، 12.5 مقابل 12.50 دولارًا). لمنتجات Pay What You Want فقط. يتم تجاهل القيمة إذا كانت أقل من الحد الأدنى لسعر المنتج.
  • string
    حقول البيانات الوصفية المخصصة (مثلًا، metadata_orderId=123).
paymentAmount في رابط الدفع ليست الوحدة نفسها الموجودة في الحقل amount في Checkout Sessions API. تستخدم معلمة الرابط وحدات العملة الرئيسية (12.5 = 12.50 دولارًا)، بينما تستخدم product_cart[].amount في API أصغر فئة نقدية (1250 = 12.50 دولارًا). راجع التسعير الديناميكي للاطلاع على حقل API.
6

Share the link

أرسل رابط الدفع المكتمل إلى عميلك. عند زيارته، يتم جمع جميع معلمات الاستعلام وتخزينها مع معرّف جلسة. بعد ذلك، يتم تبسيط عنوان URL ليشمل معلمة الجلسة فقط (مثلًا، ?session=sess_1a2b3c4d). تستمر المعلومات المخزنة عبر عمليات تحديث الصفحة، ويمكن الوصول إليها طوال عملية الدفع.
أصبحت تجربة الدفع لدى العميل الآن أكثر سلاسة وتخصيصًا استنادًا إلى معلماتك.

4. روابط الدفع الديناميكية

فضّل استخدام Checkout Sessions لمعظم حالات الاستخدام، إذ توفر مزيدًا من المرونة والتحكم.
يتم إنشاؤها عبر استدعاء API أو باستخدام SDK الخاص بنا مع تفاصيل العميل. إليك مثالًا: هناك واجهتا API لإنشاء روابط الدفع الديناميكية:
  • واجهة API لرابط الدفع لمرة واحدة مرجع API
  • واجهة API لرابط دفع الاشتراك مرجع API
نقطتا النهاية لإنشاء الروابط متوقفتان. يواصل POST /payments وPOST /subscriptions العمل مع عمليات التكامل الحالية، ولكن يجب أن تستخدم عمليات التكامل الجديدة Checkout Sessions (POST /checkouts) بدلًا منهما.
الدليل أدناه مخصص لإنشاء رابط دفع لمرة واحدة. للحصول على تعليمات مفصلة حول تكامل الاشتراكات، راجع دليل تكامل الاشتراكات.
تأكد من تمرير payment_link = true للحصول على رابط الدفع
بعد إنشاء رابط الدفع، أعد توجيه عملائك لإكمال عملية الدفع.

تنفيذ Webhooks

أنشئ نقطة نهاية API لتلقي إشعارات الدفع. إليك مثالًا باستخدام Next.js:
يتبع تنفيذ webhook لدينا مواصفات Standard Webhooks. للاطلاع على تعريفات أنواع webhook، راجع دليل أحداث Webhook.

الأحداث التي يجب الاستماع إليها

فعّل payload.type وتعامل مع الأحداث ذات الصلة بتدفق الدفع لمرة واحدة. استمع على الأقل إلى ما يلي:
نفّذ الطلب دائمًا عند ورود payment.succeeded من webhook، وليس عند إعادة التوجيه في المتصفح — فقد لا تتم إعادة التوجيه إذا أغلق العميل علامة التبويب، بينما يُعاد إرسال webhook حتى يتم الإقرار باستلامه.
إذا كنت تبيع منتجات رقمية تتضمن مفاتيح ترخيص، فعليك أيضًا التعامل مع license_key.created. للحصول على القائمة الكاملة للأحداث — بما في ذلك أحداث الاشتراك والاستحقاق والرصيد والاسترداد والتحصيل المتأخر — راجع دليل أحداث Webhook. يمكنك الرجوع إلى هذا المشروع الذي يتضمن تنفيذًا تجريبيًا على GitHub باستخدام Next.js وTypeScript. يمكنك الاطلاع على التنفيذ المباشر هنا.

أهم الأمور التي يجب معرفتها حول Checkout والعملة

تكون المبالغ الديناميكية (Pay-What-You-Want) بعملة المنتج الأساسية — وليست بعملة محلية عشوائية — كما أن العملة الأساسية تقتصر على USD وINR وGBP وEUR. لتحصيل مبلغ ثابت بعملة أخرى (مثل PHP)، لا يمكنك تمريره مباشرة: استخدم Adaptive Pricing (يحوّل المبلغ الأساسي وفق أسعار الصرف المباشرة) أو Localized Pricing (سعر ثابت لكل عملة، لكنه غير متوافق مع Pay-What-You-Want).
حدّد العملة صراحةً. مرّر billing_currency وbilling_address.country في جلسة الدفع. إذا لم تُمرَّر، يتم اكتشاف العملة والبلد من عنوان IP الخاص بالعميل (Adaptive Currency)، وقد لا يتطابقان مع ما تنوي تحصيله.
تنتهي صلاحية جلسات الدفع خلال 24 ساعة (15 دقيقة عند confirm: true)، وكل checkout_url مخصص للاستخدام مرة واحدة — أنشئ جلسة جديدة لكل عميل ولكل محاولة دفع بدلًا من إعادة استخدام الرابط.
الشراء المتكرر بنقرة واحدة. بالنسبة إلى عميل عائد لديه طريقة دفع محفوظة، مرّر payment_method_id مع confirm: true لتحصيل المبلغ فورًا، مع تخطي اختيار الطريقة بالكامل.

مرجع API ذي الصلة

Create Checkout Session

مرجع API لإنشاء جلسات دفع آمنة ومستضافة لإجراء الدفعات لمرة واحدة والاشتراكات

Create Payment Link

مرجع API لإنشاء روابط دفع ديناميكية برمجيًا
آخر تعديل في ٢١ أغسطس ٢٠٢٦