Skip to main content

Checkout Sessions

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

Payment Links

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

Webhooks

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

API Reference

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

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

قبل البدء، تحتاج إلى:
  • حساب Dodo Payments.
  • منتج واحد على الأقل. أنشئه ضمن Products في لوحة التحكم. يجب أن يستوفي منتج الاشتراك ذي السعر غير الصفري الحد الأدنى للاشتراك للعملة التي يدفع بها العميل: $1.00 لعملة USD. يجب أيضًا أن تبلغ قيمة العملات غير USD وEUR وGBP ما لا يقل عن $1.00. كما تتوفر الاشتراكات بقيمة $0.
  • مفتاح API. أنشئه ضمن Developer → API Keys واحفظه في متغير البيئة DODO_PAYMENTS_API_KEY. أنشئ المفتاح في وضع الاختبار أثناء عملية التطوير: تستخدم الأمثلة في هذه الصفحة وضع الاختبار، ولا يعمل مفتاح وضع الاختبار إلا مع وضع الاختبار. راجع Authentication.
  • SDK للغتك. يتطلب Node.js SDK الإصدار 20 من Node.js أو إصدارًا أحدث، ويتطلب Python SDK الإصدار 3.9 من Python أو إصدارًا أحدث، ويتطلب Go SDK الإصدار 1.22 من Go أو إصدارًا أحدث. لا تتطلب أمثلة cURL أي SDK.
يستخدم مثال webhook أيضًا الحزمة standardwebhooks. ثبّتها باستخدام npm install standardwebhooks.

اختر مسار التكامل

يعمل Overlay Checkout وInline Checkout في صفحة ويب فقط. في تطبيق أصلي للأجهزة المحمولة، أنشئ جلسة Checkout على خادمك وافتح checkout_url باستخدام SDK لـ Checkout على الأجهزة المحمولة. لجعل وكيل برمجي ينشئ هذا التكامل نيابةً عنك، ثبّت Agent Plugin.

Checkout Sessions

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

إنشاء Checkout Session

إعادة التوجيه إلى Checkout

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

معالجة الأخطاء

عند فشل طلب، تُرجع API رمز حالة HTTP ونص JSON يتضمن code وmessage. اجعل تفرّع معالجة الأخطاء يعتمد على code، وليس على message. لمعرفة كل رمز وسببه وكيفية حله، راجع Error Codes. يتم الإبلاغ عن عملية الدفع الفاشلة بشكل منفصل: تكون قيمة status لعملية الدفع هي failed، ويقدم error_code السبب، وتتلقى payment.failed webhook. لتحديد ما إذا كان ينبغي إعادة المحاولة، راجع Handle Payment Failures. رابط الدفع هو عنوان URL يفتح Checkout لمنتج، ما يتيح لك تحصيل المدفوعات من دون كتابة تعليمات برمجية. تملأ معلمات الاستعلام مسبقًا تفاصيل العميل وتتحكم في نموذج Checkout. عند فتح العميل للرابط، يخزن Checkout المعلمات في جلسة ويختصر عنوان URL إلى معلمة session، لذلك يحتفظ بها تحديث الصفحة.

روابط الدفع الثابتة

رابط الدفع الثابت هو عنوان URL تنشئه مرة واحدة وتشاركه عدة مرات. عنوان URL الأساسي هو:
أضف معلمات استعلام لتخصيص Checkout:
integer
افتراضي:"1"
عدد العناصر المطلوب شراؤها.
string
مطلوب
تستخدم Payment Links القيمة redirect_url. وتستخدم API الخاصة بـ Checkout Sessions القيمة 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). ويستخدم حقل API الخاص بـ Checkout Sessions، product_cart[].amount، أصغر وحدة للعملة (يمثل 1250 مبلغ $12.50). راجع Dynamic Pricing.
string
حقول بيانات وصفية مخصصة، مثل metadata_orderId=123.

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

أضف حقول العميل كمعلمات استعلام لتبسيط Checkout:
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 إلى Create One-Time Payment أو Create Subscription لإنشاء رابط. تنشئ الأمثلة أدناه رابط دفع لمرة واحدة. للاشتراكات، راجع Subscription Integration Guide.

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 Event Guide. للاطلاع على مثال كامل باستخدام Next.js وTypeScript، راجع مستودع العرض التوضيحي والنشر المباشر الخاص به.

العملة وعنوان الفوترة

للتحصيل بعملة محددة، مرّر billing_currency وbilling_address.country عند إنشاء جلسة Checkout. إذا حذفتهما، تختار 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 كامل، أو country وzipcode فقط عندما تكون قيمة minimal_address هي true. تفرض الجلسة رسوم طريقة الدفع المحفوظة مباشرةً، ولذلك لا تُرجع checkout_url. استخدم webhooks لمعرفة ما إذا نجحت عملية الدفع.

صفحات ذات صلة

Checkout Sessions

دليل كامل يتضمن خيارات تخصيص متقدمة.

Overlay Checkout

تضمين Checkout كتراكب لنافذة مشروطة في صفحتك.

Inline Checkout

تضمين Checkout مباشرةً في تخطيط صفحتك.

Subscription Integration

إعداد الفوترة المتكررة.

Webhook Event Guide

القائمة الكاملة لجميع أحداث Webhook.

API Reference

توثيق API الخاصة بـ Checkout Sessions.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦