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.
standardwebhooks. ثبّتها باستخدام npm install standardwebhooks.
اختر مسار التكامل
يعمل Overlay Checkout وInline Checkout في صفحة ويب فقط. في تطبيق أصلي للأجهزة المحمولة، أنشئ جلسة Checkout على خادمك وافتح
checkout_url باستخدام SDK لـ Checkout على الأجهزة المحمولة.
لجعل وكيل برمجي ينشئ هذا التكامل نيابةً عنك، ثبّت Agent Plugin.
Checkout Sessions
أنشئ تجربة Checkout آمنة ومستضافة. تنشئ جلسة على خادمك، ثم تعيد توجيه العميل إلىcheckout_url الذي يتم إرجاعه.
إنشاء Checkout Session
- Node.js SDK
- Python SDK
- cURL
إعادة التوجيه إلى Checkout
بعد إنشاء جلسة، أعد توجيه العميل إلىcheckout_url:
معالجة الأخطاء
عند فشل طلب، تُرجع API رمز حالة HTTP ونص JSON يتضمنcode وmessage. اجعل تفرّع معالجة الأخطاء يعتمد على code، وليس على message. لمعرفة كل رمز وسببه وكيفية حله، راجع Error Codes. يتم الإبلاغ عن عملية الدفع الفاشلة بشكل منفصل: تكون قيمة status لعملية الدفع هي failed، ويقدم error_code السبب، وتتلقى payment.failed webhook. لتحديد ما إذا كان ينبغي إعادة المحاولة، راجع Handle Payment Failures.
Payment Links
رابط الدفع هو عنوان URL يفتح Checkout لمنتج، ما يتيح لك تحصيل المدفوعات من دون كتابة تعليمات برمجية. تملأ معلمات الاستعلام مسبقًا تفاصيل العميل وتتحكم في نموذج Checkout. عند فتح العميل للرابط، يخزن Checkout المعلمات في جلسة ويختصر عنوان URL إلى معلمةsession، لذلك يحتفظ بها تحديث الصفحة.
روابط الدفع الثابتة
رابط الدفع الثابت هو عنوان URL تنشئه مرة واحدة وتشاركه عدة مرات. عنوان URL الأساسي هو: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 فقط، ويتم تجاهله إذا كان أقل من الحد الأدنى لسعر المنتج.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:
مثال على رابط دفع ثابت
روابط الدفع الديناميكية (متوقفة)
بالنسبة إلى عمليات التكامل الحالية التي تستخدم روابط الدفع الديناميكية، مرّرpayment_link: true إلى Create One-Time Payment أو Create Subscription لإنشاء رابط. تنشئ الأمثلة أدناه رابط دفع لمرة واحدة. للاشتراكات، راجع Subscription Integration Guide.
- 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 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.