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

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

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

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

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

التكامل

روابط الدفع

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

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. الدفع المدمج

للحصول على تجارب دفع متكاملة مدمجة مباشرة في صفحتك، استخدم تكامل الدفع المدمج. يتيح لك ذلك بناء ملخصات الطلبات المخصصة والتحكم الكامل في تخطيط الدفع بينما تتولى Dodo Payments جمع المدفوعات بشكل آمن.

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

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

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

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

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

قم بتضمين معلمات الاستعلام الأساسية:
  • quantity
    integer
    افتراضي:"1"
    عدد العناصر المراد شراؤها.
  • redirect_url
    string
    مطلوب
    عنوان 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
    الرمز البريدي/ZIP.
  • 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
    افتراضي:"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();
بعد إنشاء رابط الدفع، قم بإعادة توجيه عملائك لإكمال دفعهم.

تنفيذ Webhooks

قم بإعداد نقطة نهاية 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
}
تتبع تنفيذ webhook الخاص بنا مواصفات Webhooks القياسية. للحصول على تعريفات أنواع webhook، يرجى الرجوع إلى دليل أحداث Webhook. يمكنك الرجوع إلى هذا المشروع مع تنفيذ تجريبي على GitHub باستخدام Next.js و TypeScript. يمكنك الاطلاع على التنفيذ المباشر هنا.