المتطلبات الأساسية
لدمج واجهة برمجة تطبيقات Dodo Payments، ستحتاج إلى:- حساب تاجر على Dodo Payments
- بيانات اعتماد API (مفتاح API ومفتاح سر webhook) من لوحة التحكم
إعداد لوحة التحكم
- انتقل إلى لوحة تحكم Dodo Payments
- أنشئ منتجًا (دفعة لمرة واحدة أو اشتراك). يجب ألا يقل سعر منتجات الاشتراك عن $1 (أو ما يعادله بالعملة التي اخترتها)؛ ولا تُدعم المبالغ الأقل من هذا الحد الأدنى.
-
أنشئ مفتاح API:
- انتقل إلى Developer > API
- دليل تفصيلي
- انسخ مفتاح API إلى البيئة المسماة DODO_PAYMENTS_API_KEY
-
اضبط webhooks:
- انتقل إلى Developer > Webhooks
- أنشئ عنوان URL لـ webhook لإشعارات الدفع
- انسخ مفتاح webhook السري إلى البيئة
التكامل
Payment Links
اختر مسار التكامل الذي يناسب حالة استخدامك:- 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.
- Node.js SDK
- Python SDK
- REST API
2
Redirect customer to checkout
بعد إنشاء الجلسة، أعد التوجيه إلى
checkout_url لبدء التدفق المستضاف.2. Overlay Checkout
لتوفير تجربة دفع سلسة داخل الصفحة، استكشف تكامل Overlay Checkout الذي يتيح للعملاء إتمام المدفوعات دون مغادرة موقعك.3. Inline Checkout
لتوفير تجارب دفع متكاملة مضمّنة مباشرةً في صفحتك، استخدم تكامل Inline Checkout. يتيح لك ذلك إنشاء ملخصات طلبات مخصصة والتحكم الكامل في تخطيط صفحة الدفع، بينما تتولى Dodo Payments تحصيل المدفوعات بأمان.4. Static Payment Links
تتيح لك روابط الدفع الثابتة قبول المدفوعات بسرعة عبر مشاركة عنوان URL بسيط. يمكنك تخصيص تجربة الدفع بتمرير query parameters لملء تفاصيل العميل مسبقًا، والتحكم في حقول النموذج، وإضافة بيانات وصفية مخصصة.1
Construct your payment link
ابدأ بعنوان URL الأساسي وألحق به معرّف منتجك:
2
Add core parameters
أدرج query parameters الأساسية:
-
integerافتراضي:"1"عدد العناصر المطلوب شراؤها.
-
stringمطلوبعنوان URL لإعادة التوجيه بعد اكتمال الدفع.
سيتضمن عنوان URL لإعادة التوجيه تفاصيل الدفع بوصفها query parameters، مثل:
إذا كانت مفاتيح الترخيص مفعّلة للمنتج، فسيُضاف أيضًا parameter باسم
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.com3
Pre-fill customer information (optional)
أضف حقول العميل أو الفوترة كـ query parameters لتبسيط عملية الدفع.
Supported Customer Fields
Supported Customer Fields
4
Control form fields (optional)
يمكنك تعطيل حقول محددة لجعلها للقراءة فقط بالنسبة إلى العميل. يفيد ذلك عندما تكون لديك تفاصيل العميل مسبقًا، مثل المستخدمين الذين سجّلوا الدخول.
disable… المقابلة على true:- Disable Flags Table
يؤدي ضبط
showDiscounts=false إلى تعطيل قسم الخصومات وإخفائه في نموذج الدفع. استخدم ذلك إذا أردت منع العملاء من إدخال رموز القسائم أو الرموز الترويجية أثناء الدفع.5
6
Share the link
أرسل رابط الدفع المكتمل إلى عميلك. عند زيارته، تُجمع جميع query parameters وتُخزّن مع معرّف جلسة. ثم يُبسّط عنوان URL ليشمل parameter الجلسة فقط (مثل
?session=sess_1a2b3c4d). وتستمر المعلومات المخزنة عبر عمليات تحديث الصفحة، ويمكن الوصول إليها طوال عملية الدفع.أصبحت تجربة الدفع لدى العميل الآن أكثر سلاسة وتخصيصًا استنادًا إلى parameters التي مرّرتها.
4. Dynamic Payment Links
يتم إنشاؤها عبر استدعاء API أو باستخدام SDK الخاص بنا مع تفاصيل العميل. إليك مثالًا: هناك واجهتا API لإنشاء روابط الدفع الديناميكية: الدليل أدناه مخصص لإنشاء رابط دفع لمرة واحدة. للحصول على تعليمات تفصيلية حول دمج الاشتراكات، راجع دليل دمج الاشتراكات.تأكد من تمرير
payment_link = true للحصول على رابط الدفع - Node.js SDK
- Python SDK
- Go SDK
- Api Reference
بعد إنشاء رابط الدفع، أعد توجيه عملائك لإكمال عملية الدفع.
تنفيذ Webhooks
أنشئ endpoint في API لاستقبال إشعارات الدفع. إليك مثالًا باستخدام Next.js:الأحداث التي يجب الاستماع إليها
فعّلpayload.type وتعامل مع الأحداث ذات الصلة بتدفق الدفع لمرة واحدة. استمع إلى الأحداث التالية على الأقل:
إذا كنت تبيع منتجات رقمية باستخدام مفاتيح ترخيص، فعليك أيضًا التعامل مع
license_key.created. للحصول على القائمة الكاملة للأحداث — بما في ذلك أحداث الاشتراك والاستحقاق والرصيد والاسترداد والتحصيل — راجع دليل أحداث Webhook.
يمكنك الرجوع إلى هذا المشروع الذي يتضمن تنفيذًا تجريبيًا على GitHub باستخدام Next.js وTypeScript.
يمكنك الاطلاع على التنفيذ المباشر هنا.
أهم الأمور التي يجب معرفتها حول Checkout والعملة
تنتهي صلاحية جلسات الدفع خلال 24 ساعة (15 دقيقة عند
confirm: true)، ويُعد كل checkout_url للاستخدام مرة واحدة — أنشئ جلسة جديدة لكل عميل ولكل محاولة دفع بدلًا من إعادة استخدام الرابط.الشراء المتكرر بنقرة واحدة. بالنسبة إلى عميل عائد لديه طريقة دفع محفوظة، مرّر
payment_method_id مع confirm: true لتحصيل المبلغ فورًا، مع تخطي اختيار الطريقة بالكامل.مرجع API ذي صلة
Create Checkout Session
مرجع API لإنشاء جلسات دفع آمنة ومستضافة للدفعات لمرة واحدة والاشتراكات
Create Payment Link
مرجع API لإنشاء روابط دفع ديناميكية برمجيًا