Skip to main content

Checkout Sessions

أنشئ صفحة دفع مستضافة وآمنة للمدفوعات لمرة واحدة والاشتراكات.

Payment Links

شارك عنوان URL لتحصيل المدفوعات بدون كتابة أي كود.

Webhooks

استمع إلى أحداث الدفع ونفّذ الطلبات.

API Reference

توثيق شامل لنقاط النهاية واختبار مباشر.

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

قبل البدء، تحتاج إلى:
  • حساب Dodo Payments.
  • منتج واحد على الأقل. أنشئه ضمن Products في لوحة التحكم. يجب أن يكون سعر منتج الاشتراك ذي السعر غير الصفري 1أوأكثر،أومايعادلهبعملةالمنتج.الاشتراكبقيمة1 أو أكثر، أو ما يعادله بعملة المنتج. الاشتراك بقيمة 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_url مرة واحدة وتنتهي صلاحيته بعد 24 ساعة، أو بعد 15 دقيقة عند تمرير confirm: true. عند استخدام confirm: true، يجب أيضًا تقديم كل حقل مطلوب. أنشئ جلسة جديدة لكل عميل ولكل محاولة دفع.

إنشاء Checkout Session

إعادة التوجيه إلى صفحة الدفع

بعد إنشاء الجلسة، أعد توجيه العميل إلى checkout_url:
للتخصيص المتقدم، راجع دليل Checkout Sessions الكامل ومرجع API.
رابط الدفع هو عنوان 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 فقط، ويتم تجاهله إذا كان أقل من الحد الأدنى لسعر المنتج.
يستخدم paymentAmount وحدات العملة الأساسية (12.5 هو 12.50).يستخدمحقلCheckoutSessionsAPI‏‘productcart[].amount‘أصغروحدةللعملة(‘1250‘هو12.50). يستخدم حقل Checkout Sessions API ‏`product_cart[].amount` أصغر وحدة للعملة (`1250` هو 12.50). راجع التسعير الديناميكي.
string
حقول بيانات وصفية مخصصة، مثل metadata_orderId=123.

ملء معلومات العميل مسبقًا

أضف حقول العميل كمعلمات استعلام لتسهيل عملية الدفع:
string
الاسم الكامل للعميل (يُتجاهل إذا تم توفير firstName أو lastName).
string
الاسم الأول للعميل.
string
اسم عائلة العميل.
string
عنوان البريد الإلكتروني للعميل.
string
بلد العميل (رمز ISO 3166-1 alpha-2).
string
عنوان الشارع.
string
المدينة.
string
الولاية أو المقاطعة.
string
الرمز البريدي أو ZIP Code.

تعطيل حقول النموذج

لمنع العملاء من تغيير المعلومات المعبأة مسبقًا، عطّل الحقل من خلال توفير قيمته وضبط علامة disable... المقابلة على true:

مثال على رابط دفع ثابت

يمنع تعطيل الحقول التغييرات غير المقصودة ويضمن اتساق البيانات.

روابط الدفع الديناميكية (متوقفة)

نقطتا النهاية POST /payments وPOST /subscriptions متوقفتان. استخدم Checkout Sessions بدلًا منهما لعمليات التكامل الجديدة.
بالنسبة إلى عمليات التكامل الحالية التي تستخدم روابط الدفع الديناميكية، مرّر payment_link: true إلى إنشاء دفعة لمرة واحدة أو إنشاء اشتراك لإنشاء رابط. تنشئ الأمثلة أدناه رابط دفع لمرة واحدة. للاشتراكات، راجع دليل تكامل الاشتراكات.

Webhooks

تُعلم webhooks خادمك بنجاح الدفع أو فشله، حتى تتمكن من تنفيذ الطلب.

إنشاء نقطة نهاية Webhook

انتقل إلى Developer → Webhooks في لوحة التحكم وأضف عنوان URL لنقطة النهاية. انسخ سر توقيع نقطة النهاية إلى متغير البيئة DODO_PAYMENTS_WEBHOOK_KEY. إليك مثالًا باستخدام Next.js:
app/api/webhooks/dodo/route.ts
يتبع تنفيذ webhook لدينا مواصفات Standard Webhooks.

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

كحد أدنى، استمع إلى هذه الأحداث في تدفق دفع لمرة واحدة:
نفّذ الطلب دائمًا عند payment.succeeded الوارد من webhook، وليس عند إعادة توجيه المتصفح. قد لا تحدث إعادة التوجيه إذا أغلق العميل علامة التبويب، بينما يُعاد إرسال webhook حتى يتم تأكيد استلامه.
إذا كنت تبيع منتجات تحتوي على مفاتيح ترخيص، فعليك أيضًا معالجة 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.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦