الانتقال إلى المحتوى الرئيسي

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

لدمج واجهة برمجة تطبيقات مدفوعات دودي، ستحتاج إلى:
  • حساب تاجر مدفوعات دودي
  • بيانات اعتماد API (مفتاح API ومفتاح سري للويب هوك) من لوحة التحكم

إعداد لوحة التحكم

  1. انتقل إلى لوحة تحكم مدفوعات دودي
  2. أنشئ منتجًا (مدفوعات لمرة واحدة أو اشتراك)
  3. قم بإنشاء مفتاح API الخاص بك:
    • انتقل إلى المطور > API
    • دليل مفصل
    • انسخ مفتاح API في البيئة المسماة DODO_PAYMENTS_API_KEY
  4. قم بتكوين الويب هوكس:
    • انتقل إلى المطور > الويب هوكس
    • أنشئ عنوان URL للويب هوك لإشعارات الدفع
    • انسخ مفتاح الويب هوك السري في البيئة

التكامل

روابط الدفع

اختر مسار التكامل الذي يناسب حالتك:
  • جلسات الدفع (موصى بها): الأفضل لمعظم عمليات التكامل. أنشئ جلسة على خادمك وأعد توجيه العملاء إلى عملية دفع آمنة ومستضافة.
  • الدفع المدمج (Overlay Checkout): استخدمه عندما تحتاج إلى تجربة داخل الصفحة تدمج عملية الدفع المستضافة في موقعك.
  • روابط الدفع الثابتة: روابط قابلة للمشاركة على الفور بدون كود لجمع المدفوعات بسرعة.
  • روابط الدفع الديناميكية: روابط تم إنشاؤها برمجيًا. ومع ذلك، يُوصى بجلسات الدفع لأنها توفر مزيدًا من المرونة.

1. جلسات الدفع

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

إنشاء جلسة دفع

اختر SDK المفضل لديك أو اتصل بواجهة برمجة التطبيقات REST.
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customer: { email: '[email protected]', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});
2

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

بعد إنشاء الجلسة، أعد توجيه إلى checkout_url لبدء العملية المستضافة.
// Example in a browser context
window.location.href = session.checkout_url;
يفضل استخدام جلسات الدفع كأسرع وأضمن طريقة لبدء قبول المدفوعات. لمزيد من التخصيص المتقدم، راجع الدليل الكامل لـ جلسات الدفع و مرجع API.

2. الدفع المدمج (Overlay Checkout)

للحصول على تجربة دفع سلسة داخل الصفحة، استكشف تكامل الدفع المدمج الذي يسمح للعملاء بإكمال المدفوعات دون مغادرة موقعك.

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

تتيح لك روابط الدفع الثابتة قبول المدفوعات بسرعة من خلال مشاركة عنوان URL بسيط. يمكنك تخصيص تجربة الدفع عن طريق تمرير معلمات الاستعلام لملء تفاصيل العميل مسبقًا، والتحكم في حقول النموذج، وإضافة بيانات وصفية مخصصة.
1

إنشاء رابط الدفع الخاص بك

ابدأ بعنوان URL الأساسي وأضف معرف المنتج الخاص بك:
https://checkout.dodopayments.com/buy/{productid}
2

إضافة المعلمات الأساسية

قم بتضمين معلمات الاستعلام الأساسية:
  • quantity
    integer
    default:"1"
    عدد العناصر المراد شراؤها.
  • redirect_url
    string
    required
    عنوان URL لإعادة التوجيه بعد إتمام الدفع.
سيشمل عنوان URL لإعادة التوجيه تفاصيل الدفع كمعلمات استعلام، على سبيل المثال:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded
3

ملء معلومات العميل مسبقًا (اختياري)

أضف حقول العميل أو الفوترة كمعلمات استعلام لتبسيط عملية الدفع.
  • fullName
    string
    الاسم الكامل للعميل (يتم تجاهله إذا تم توفير firstName أو lastName).
  • firstName
    string
    الاسم الأول للعميل.
  • lastName
    string
    اسم العائلة للعميل.
  • email
    string
    البريد الإلكتروني للعميل.
  • country
    string
    بلد العميل.
  • addressLine
    string
    عنوان الشارع.
  • city
    string
    المدينة.
  • state
    string
    الولاية أو المقاطعة.
  • zipCode
    string
    الرمز البريدي.
  • showDiscounts
    boolean
    true أو false
4

التحكم في حقول النموذج (اختياري)

يمكنك تعطيل حقول معينة لجعلها للقراءة فقط للعميل. هذا مفيد عندما يكون لديك تفاصيل العميل بالفعل (مثل المستخدمين المسجلين).
لتعطيل حقل، قدم قيمته واضبط علامة disable… المقابلة على true:
&[email protected]&disableEmail=true
الحقلعلامة التعطيلالمعلمة المطلوبة
الاسم الكاملdisableFullNamefullName
الاسم الأولdisableFirstNamefirstName
اسم العائلةdisableLastNamelastName
البريد الإلكترونيdisableEmailemail
البلدdisableCountrycountry
عنوان الشارعdisableAddressLineaddressLine
المدينةdisableCitycity
الولايةdisableStatestate
الرمز البريديdisableZipCodezipCode
يساعد تعطيل الحقول في منع التغييرات غير المقصودة وضمان اتساق البيانات.
تعيين showDiscounts=false سيعطل ويخفي قسم الخصومات في نموذج الدفع. استخدم هذا إذا كنت ترغب في منع العملاء من إدخال رموز القسيمة أو الرموز الترويجية أثناء الدفع.
5

إضافة عناصر تحكم متقدمة (اختياري)

  • paymentCurrency
    string
    تحديد عملة الدفع. الافتراضي هو عملة بلد الفوترة.
  • showCurrencySelector
    boolean
    default:"true"
    إظهار أو إخفاء محدد العملة.
  • paymentAmount
    integer
    المبلغ بالسنت (لأسعار الدفع التي تريدها فقط).
  • metadata_*
    string
    حقول بيانات وصفية مخصصة (مثل metadata_orderId=123).
6

مشاركة الرابط

أرسل رابط الدفع المكتمل إلى عميلك. عندما يزورونه، يتم جمع جميع معلمات الاستعلام وتخزينها مع معرف الجلسة. ثم يتم تبسيط عنوان URL ليشمل فقط معلمة الجلسة (على سبيل المثال، ?session=sess_1a2b3c4d). تستمر المعلومات المخزنة عبر تحديثات الصفحة وتكون متاحة طوال عملية الدفع.
تجربة الدفع للعميل الآن سلسة ومخصصة بناءً على معلماتك.

4. روابط الدفع الديناميكية

يفضل استخدام جلسات الدفع لمعظم حالات الاستخدام، حيث توفر مزيدًا من المرونة والتحكم.
تم إنشاؤها عبر استدعاء API أو SDK الخاص بنا مع تفاصيل العميل. إليك مثال: هناك واجهتان برمجيتان لإنشاء روابط الدفع الديناميكية:
  • واجهة برمجة تطبيقات رابط الدفع لمرة واحدة مرجع API
  • واجهة برمجة تطبيقات رابط الدفع للاشتراك مرجع API
الدليل أدناه هو لإنشاء رابط الدفع لمرة واحدة. للحصول على تعليمات مفصلة حول دمج الاشتراكات، راجع دليل تكامل الاشتراك.
تأكد من أنك تمرر payment_link = true للحصول على رابط الدفع
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: '[email protected]', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();
بعد إنشاء رابط الدفع، أعد توجيه عملائك لإكمال دفعهم.

تنفيذ الويب هوكس

قم بإعداد نقطة نهاية API لتلقي إشعارات الدفع. إليك مثال باستخدام Next.js:
import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}
تتبع تنفيذ الويب هوك لدينا مواصفات الويب هوكس القياسية. للحصول على تعريفات أنواع الويب هوك، راجع دليل أحداث الويب هوك. يمكنك الرجوع إلى هذا المشروع مع تنفيذ تجريبي على GitHub باستخدام Next.js وTypeScript. يمكنك الاطلاع على التنفيذ المباشر هنا.