Checkout Sessions
أنشئ صفحة دفع مستضافة وآمنة للمدفوعات لمرة واحدة والاشتراكات.
Payment Links
شارك عنوان URL لتحصيل المدفوعات بدون كتابة أي كود.
Webhooks
استمع إلى أحداث الدفع ونفّذ الطلبات.
API Reference
توثيق شامل لنقاط النهاية واختبار مباشر.
المتطلبات الأساسية
قبل البدء، تحتاج إلى:- حساب Dodo Payments.
- منتج واحد على الأقل. أنشئه ضمن Products في لوحة التحكم. يجب أن يكون سعر منتج الاشتراك ذي السعر غير الصفري 0 مدعوم أيضًا.
- مفتاح API. أنشئه ضمن Developer → API Keys وخزّنه في متغير البيئة
DODO_PAYMENTS_API_KEY. أنشئ المفتاح في وضع الاختبار أثناء عملية البناء: تستخدم الأمثلة في هذه الصفحة وضع الاختبار، ويعمل مفتاح وضع الاختبار مع وضع الاختبار فقط. راجع المصادقة.
اختر مسار التكامل
يعمل Overlay checkout وInline checkout في صفحة ويب فقط. في تطبيق جوّال أصلي، أنشئ جلسة الدفع على خادمك وافتح
checkout_url باستخدام Mobile checkout SDK.
لجعل وكيل برمجي ينشئ هذا التكامل نيابةً عنك، ثبّت Agent Plugin.
Checkout Sessions
أنشئ تجربة دفع مستضافة وآمنة. تنشئ جلسة على خادمك، ثم تعيد توجيه العميل إلىcheckout_url المُعاد.
إنشاء Checkout Session
- Node.js SDK
- Python SDK
- cURL
إعادة التوجيه إلى صفحة الدفع
بعد إنشاء الجلسة، أعد توجيه العميل إلىcheckout_url:
Payment Links
رابط الدفع هو عنوان URL يفتح صفحة الدفع لمنتج، ما يتيح لك تحصيل المدفوعات دون كتابة كود. تملأ معلمات الاستعلام تفاصيل العميل مسبقًا وتتحكم في نموذج الدفع. عند فتح العميل للرابط، تحفظ صفحة الدفع المعلمات في جلسة وتختصر عنوان URL إلى معلمةsession، لذلك تحتفظ عملية تحديث الصفحة بها.
روابط الدفع الثابتة
رابط الدفع الثابت هو عنوان URL تنشئه مرة واحدة وتشاركه عدة مرات. عنوان URL الأساسي هو:integer
افتراضي:"1"
عدد العناصر المطلوب شراؤها.
string
مطلوب
تستخدم روابط الدفع
redirect_url. تستخدم Checkout Sessions API return_url للغرض نفسه.عنوان URL لإعادة التوجيه إليه بعد الدفع. يُلحق Dodo Payments تفاصيل الدفع كمعلمات استعلام، مثل https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. إذا كان المنتج يُصدر مفاتيح ترخيص، تُلحق أيضًا معلمة license_key، مع فصل المفاتيح المتعددة بفواصل.string
تحدد عملة الدفع. القيمة الافتراضية هي عملة بلد الفوترة.
boolean
افتراضي:"true"
إظهار محدد العملة أو إخفاؤه.
boolean
افتراضي:"true"
إظهار قسم الخصومات أو إخفاؤه. اضبطه على
false لمنع العملاء من إدخال رموز القسائم.number
يثبت المبلغ المُحصّل، بوحدات العملة الأساسية، مثل
12.5 لـ $12.50. يعمل مع منتجات Pay What You Want فقط، ويتم تجاهله إذا كان أقل من الحد الأدنى لسعر المنتج.string
حقول بيانات وصفية مخصصة، مثل
metadata_orderId=123.ملء معلومات العميل مسبقًا
أضف حقول العميل كمعلمات استعلام لتسهيل عملية الدفع:string
الاسم الكامل للعميل (يُتجاهل إذا تم توفير firstName أو lastName).
string
الاسم الأول للعميل.
string
اسم عائلة العميل.
string
عنوان البريد الإلكتروني للعميل.
string
بلد العميل (رمز ISO 3166-1 alpha-2).
string
عنوان الشارع.
string
المدينة.
string
الولاية أو المقاطعة.
string
الرمز البريدي أو ZIP Code.
تعطيل حقول النموذج
لمنع العملاء من تغيير المعلومات المعبأة مسبقًا، عطّل الحقل من خلال توفير قيمته وضبط علامةdisable... المقابلة على true:
مثال على رابط دفع ثابت
روابط الدفع الديناميكية (متوقفة)
بالنسبة إلى عمليات التكامل الحالية التي تستخدم روابط الدفع الديناميكية، مرّرpayment_link: true إلى إنشاء دفعة لمرة واحدة أو إنشاء اشتراك لإنشاء رابط. تنشئ الأمثلة أدناه رابط دفع لمرة واحدة. للاشتراكات، راجع دليل تكامل الاشتراكات.
- Node.js SDK
- Python SDK
- Go SDK
Webhooks
تُعلم webhooks خادمك بنجاح الدفع أو فشله، حتى تتمكن من تنفيذ الطلب.إنشاء نقطة نهاية Webhook
انتقل إلى Developer → Webhooks في لوحة التحكم وأضف عنوان URL لنقطة النهاية. انسخ سر توقيع نقطة النهاية إلى متغير البيئةDODO_PAYMENTS_WEBHOOK_KEY.
إليك مثالًا باستخدام Next.js:
app/api/webhooks/dodo/route.ts
الأحداث التي يجب الاستماع إليها
كحد أدنى، استمع إلى هذه الأحداث في تدفق دفع لمرة واحدة:
إذا كنت تبيع منتجات تحتوي على مفاتيح ترخيص، فعليك أيضًا معالجة
license_key.created. للحصول على القائمة الكاملة للأحداث، بما في ذلك أحداث الاشتراك والاستحقاق والرصيد والاسترداد والتحصيل، راجع دليل أحداث Webhook.
للحصول على مثال كامل باستخدام Next.js وTypeScript، راجع المستودع التجريبي والنشر المباشر.
العملة وعنوان الفوترة
للتحصيل بعملة محددة، مرّرbilling_currency وbilling_address.country عند إنشاء جلسة الدفع. إذا حذفتهما، تحدد Adaptive Currency العملة والبلد من عنوان IP الخاص بالعميل، وقد لا تكون هذه هي العملة التي تقصد التحصيل بها.
تكون مبالغ Pay What You Want بعملة المنتج الأساسية، التي يجب أن تكون USD أو GBP أو EUR. لتحصيل مبلغ ثابت بعملة أخرى، استخدم Adaptive Currency، التي تحوّل سعرك الأساسي وفق أسعار الصرف المباشرة، أو Localized Pricing، التي تحدد سعرًا ثابتًا لكل عملة. لا تعمل Localized Pricing مع Pay What You Want.
الشراء المتكرر بنقرة واحدة
لتحصيل دفعة من عميل عائد باستخدام طريقة دفع محفوظة، مرّرpayment_method_id مع confirm: true. لا تُقبل payment_method_id إلا عندما تكون confirm هي true، ويجب أيضًا تمرير customer_id الخاص بالعميل الحالي. وبما أن confirm هي true، يجب أيضًا تمرير billing_address كامل. تفرض الجلسة الرسوم مباشرةً على طريقة الدفع المحفوظة، ولذلك لا تُعيد checkout_url. استخدم webhooks لمعرفة ما إذا نجحت عملية الدفع.
صفحات ذات صلة
Checkout Sessions
دليل كامل مع خيارات تخصيص متقدمة.
Overlay Checkout
ضمّن صفحة الدفع كطبقة نافذة منبثقة في صفحتك.
Inline Checkout
ضمّن صفحة الدفع مباشرةً في تخطيط صفحتك.
Subscription Integration
أعد إعداد الفوترة المتكررة.
Webhook Event Guide
القائمة الكاملة لجميع أحداث webhook.
API Reference
توثيق Checkout Sessions API.