مرجع API - Dodo Payments Documentation

SDKs & Libraries

حِزم SDK الرسمية للواجهة الخلفية للغات TypeScript وPython وGo وPHP وJava وKotlin وC# وRuby وRust. تتولى هذه المكتبات المصادقة والتسلسل ومعالجة الأخطاء، حتى تتمكن من التركيز على عملية التكامل.

Mobile Checkout SDKs

افتح صفحة الدفع المستضافة من Dodo من تطبيقات Android وiOS وReact Native وFlutter، واحصل على نتيجة مكتوبة النوع في استدعاء واحد. لا تحتوي حِزم SDK هذه على API key.

عناوين URL للبيئات

وضع الاختبار: https://test.dodopayments.com
الوضع المباشر: https://live.dodopayments.com

تعرّف على المزيد حول وضع الاختبار مقابل الوضع المباشر.

المصادقة

تتطلب طلبات API مفتاح API، باستثناء بعض نقاط النهاية العامة مثل تفعيل الترخيص، والتحقق من صحة الترخيص، وإلغاء تفعيل الترخيص. أنشئ مفتاحًا في لوحة التحكم وأدرجه في ترويسة Authorization لكل طلب.

Generate an API Key

انتقل إلى Developer → API Keys في لوحة التحكم، ثم اختر Add API Key. أنشئ المفتاح في الوضع الذي تريد استدعاءه: يعمل مفتاح وضع الاختبار فقط مع https://test.dodopayments.com، بينما يعمل مفتاح الوضع المباشر فقط مع https://live.dodopayments.com. امنح المفتاح اسمًا وصفيًا واختر مستوى الوصول الخاص بك:

تفعيل الوصول للكتابة محدد (افتراضيًا): أذونات كاملة للقراءة والكتابة لجميع عمليات API.
تفعيل الوصول للكتابة غير محدد: وصول للقراءة فقط. يمكنك جلب البيانات (المدفوعات والاشتراكات والعملاء والمنتجات)، لكن لا يمكنك إنشاء الموارد أو تعديلها.

ألغِ تحديد تفعيل الوصول للكتابة لعمليات التكامل التي تحتاج فقط إلى عرض البيانات، مثل أدوات التحليلات أو عمليات تكامل لوحة التحكم.

Store Your Key Securely

انسخ المفتاح فورًا. لن تتمكن من رؤيته مرة أخرى. خزّنه في متغير بيئة مثل DODO_PAYMENTS_API_KEY.

Authenticate Requests

أدرج API key في ترويسة Authorization لكل طلب:

Authorization: Bearer YOUR_API_KEY

لا تكشف API key مطلقًا في تعليمات برمجية من جهة العميل أو مستودعات عامة أو أنظمة التحكم في الإصدارات.

تنسيق الاستجابة

تعيد الطلبات الناجحة 200 أو 201 مع نص JSON، أو 204 من دون نص. تعيد الأخطاء حالة 4xx أو 5xx مع نص JSON يحتوي على code وmessage.

{
  "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
  "status": "succeeded",
  "total_amount": 2999,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "code": "INVALID_REQUEST_BODY",
  "message": "Your request body is invalid. Please check your request headers and object."
}

حدود المعدل

تفرض API حدّين في الوقت نفسه: حدًا للدفعات في الثانية وحدًا مستمرًا في الدقيقة. تنطبق الحدود على نشاطك التجاري بالكامل، عبر جميع API keys الخاصة به، وتعتمد على مستوى حدود المعدل لنشاطك التجاري.

المستوى الافتراضي

الفترة	الحد
لكل ثانية (دفعة)	40 طلبًا
لكل دقيقة (مستمر)	240 طلبًا

المستويات الأعلى

يمكن للأنشطة التجارية ذات احتياجات API المتزايدة الترقية إلى حدود معدل أعلى:

المستوى	الدفعة (لكل ثانية)	المستمر (لكل دقيقة)
افتراضي	40	240
المستوى 1	100	1,000
المستوى 2	500	5,000

لترقية مستوى حدود المعدل، أرسل بريدًا إلكترونيًا إلى support@dodopayments.com.

الطلبات غير المصادق عليها

تُحدَّد معدلات الطلبات التي لا تحتوي على API key صالح حسب عنوان IP:

الفترة	الحد
لكل ثانية (دفعة)	20 طلبًا
لكل دقيقة (مستمر)	100 طلب

ترويسات حدود المعدل

تتضمن الاستجابات ترويسات توضّح استخدامك الحالي:

X-RateLimit-Limit — الحد الأقصى للطلبات المسموح بها في الفترة الحالية.
X-RateLimit-Remaining — عدد الطلبات المتبقية قبل بلوغ الحد.
X-RateLimit-Reset — عدد الثواني المتبقية حتى إعادة تعيين الفترة الحالية.

عند تجاوز الحد، تعيد API 429 Too Many Requests. طبّق التراجع الأُسّي في منطق إعادة المحاولة.

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

لمعرفة معنى الخطأ وكيفية حله، راجع صفحات رموز الأخطاء وفشل المعاملات.

Error Codes

قائمة كاملة برموز الأخطاء ومعانيها.

Transaction Failures

مشكلات المعاملات الشائعة وكيفية التعامل معها.

Webhooks

استقبل إشعارات في الوقت الفعلي عند حدوث المدفوعات والاشتراكات والأحداث الأخرى. أعد إعداد webhooks في لوحة التحكم وتعامل مع الأحداث التي يحتاج إليها تكاملك.

Webhook Guide

أعد إعداد webhooks، وتعامل مع الأحداث، وتحقق من التوقيعات.

أدلة التكامل

ابدأ بأحد هذه الأدلة لإنشاء أول عملية تكامل لك:

One-time Payments

أنشئ جلسات الدفع وروابط الدفع وتعامل مع المدفوعات.

Subscriptions

أعد إعداد الفوترة المتكررة، وأدر الخطط، وتعامل مع أحداث دورة الحياة.

Usage-Based Billing

قِس الاستخدام واحتسب الرسوم على العملاء استنادًا إلى الاستهلاك.

Checkout Sessions

أنشئ تجارب دفع مستضافة وآمنة.

SDKs & Libraries

Mobile Checkout SDKs

​عناوين URL للبيئات

​المصادقة

​تنسيق الاستجابة

​حدود المعدل

​المستوى الافتراضي

​المستويات الأعلى

​الطلبات غير المصادق عليها

​ترويسات حدود المعدل

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

Error Codes

Transaction Failures

​Webhooks

Webhook Guide

​أدلة التكامل

One-time Payments

Subscriptions

Usage-Based Billing

Checkout Sessions

عناوين URL للبيئات

المصادقة

تنسيق الاستجابة

حدود المعدل

المستوى الافتراضي

المستويات الأعلى

الطلبات غير المصادق عليها

ترويسات حدود المعدل

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

Webhooks

أدلة التكامل