Skip to main content

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

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

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

  1. انتقل إلى لوحة تحكم Dodo Payments
  2. أنشئ منتجًا (دفعة لمرة واحدة أو اشتراك). يجب ألا يقل سعر منتجات الاشتراك عن $1 (أو ما يعادله بالعملة التي اخترتها)؛ ولا تُدعم المبالغ الأقل من هذا الحد الأدنى.
  3. أنشئ مفتاح API:
    • انتقل إلى Developer > 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"
    إظهار محدد العملة أو إخفاؤه.
  • integer
    المبلغ بالسنتات (لتسعير Pay What You Want فقط).
  • string
    حقول بيانات وصفية مخصصة (مثل metadata_orderId=123).
6

Share the link

أرسل رابط الدفع المكتمل إلى عميلك. عند زيارته، تُجمع جميع query parameters وتُخزّن مع معرّف جلسة. ثم يُبسّط عنوان URL ليشمل parameter الجلسة فقط (مثل ?session=sess_1a2b3c4d). وتستمر المعلومات المخزنة عبر عمليات تحديث الصفحة، ويمكن الوصول إليها طوال عملية الدفع.
أصبحت تجربة الدفع لدى العميل الآن أكثر سلاسة وتخصيصًا استنادًا إلى parameters التي مرّرتها.
فضّل Checkout Sessions لمعظم حالات الاستخدام، فهي توفر مرونة وتحكمًا أكبر.
يتم إنشاؤها عبر استدعاء API أو باستخدام SDK الخاص بنا مع تفاصيل العميل. إليك مثالًا: هناك واجهتا API لإنشاء روابط الدفع الديناميكية: الدليل أدناه مخصص لإنشاء رابط دفع لمرة واحدة. للحصول على تعليمات تفصيلية حول دمج الاشتراكات، راجع دليل دمج الاشتراكات.
تأكد من تمرير payment_link = true للحصول على رابط الدفع
بعد إنشاء رابط الدفع، أعد توجيه عملائك لإكمال عملية الدفع.

تنفيذ Webhooks

أنشئ endpoint في 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 لإنشاء روابط دفع ديناميكية برمجيًا
آخر تعديل في ٣١ يوليو ٢٠٢٦