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

​
نظرة عامة

يوفر SDK للدفع عبر Dodo طريقة سلسة لدمج واجهة الدفع الخاصة بنا في تطبيق الويب الخاص بك. تم بناؤه باستخدام TypeScript ومعايير الويب الحديثة، ويقدم حلاً قويًا للتعامل مع المدفوعات مع معالجة الأحداث في الوقت الحقيقي وسمات قابلة للتخصيص.
صورة غلاف الدفع عبر Overlay

​
عرض تجريبي

عرض تفاعلي

شاهد الدفع عبر Overlay في العمل مع العرض التجريبي المباشر لدينا.

​
بدء سريع

ابدأ مع SDK للدفع عبر Dodo في بضع أسطر من التعليمات البرمجية: 
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
احصل على عنوان URL الخاص بالدفع من API إنشاء جلسة الدفع.

​
دليل تكامل خطوة بخطوة

1

تثبيت SDK

قم بتثبيت SDK للدفع عبر Dodo باستخدام مدير الحزم المفضل لديك:
npm install dodopayments-checkout
2

تهيئة SDK

قم بتهيئة SDK في تطبيقك، عادةً في المكون الرئيسي أو نقطة دخول التطبيق:
import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});
قم دائمًا بتهيئة SDK قبل محاولة فتح واجهة الدفع. يجب أن تتم التهيئة مرة واحدة عند تحميل تطبيقك.
3

إنشاء مكون زر الدفع

قم بإنشاء مكون يفتح واجهة الدفع:
// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}
4

إضافة الدفع إلى صفحتك

استخدم مكون زر الدفع في تطبيقك:
// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}
5

معالجة صفحات النجاح والفشل

قم بإنشاء صفحات لمعالجة إعادة التوجيه بعد الدفع:
// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful!</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}
6

اختبر تكاملك

  1. ابدأ خادم التطوير الخاص بك:
npm run dev
  1. اختبر تدفق الدفع:
    • انقر على زر الدفع
    • تحقق من ظهور واجهة الدفع
    • اختبر تدفق الدفع باستخدام بيانات اعتماد اختبار
    • تأكد من أن إعادة التوجيه تعمل بشكل صحيح
يجب أن ترى أحداث الدفع مسجلة في وحدة تحكم المتصفح لديك.
7

الانتقال إلى الإنتاج

عندما تكون جاهزًا للإنتاج:
  1. قم بتغيير الوضع إلى 'live':
DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. قم بتحديث عناوين URL الخاصة بالدفع لاستخدام جلسات الدفع الحية من الخلفية الخاصة بك
  2. اختبر التدفق الكامل في الإنتاج
  3. راقب الأحداث والأخطاء

​
مرجع API

​
التكوين

​
خيارات التهيئة

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
الخيارالنوعمطلوبالوصف
mode"test" | "live"نعموضع البيئة: 'test' للتطوير، 'live' للإنتاج
displayType"overlay" | "inline"لانوع العرض: 'overlay' للدفع في نافذة منبثقة (افتراضي)، 'inline' للدفع المدمج
onEventfunctionنعمدالة رد النداء لمعالجة أحداث الدفع

​
خيارات الدفع

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}
الخيارالنوعمطلوبالوصف
checkoutUrlstringنعمعنوان URL لجلسة الدفع من واجهة برمجة التطبيقات لإنشاء جلسات الدفع
options.showTimerbooleanلاعرض أو إخفاء مؤقت الدفع. الافتراضي هو true. عند تعطيله، ستتلقى حدث checkout.link_expired عند انتهاء الجلسة.
options.showSecurityBadgebooleanلاعرض أو إخفاء شارة الأمان. الافتراضي هو true.
options.manualRedirectbooleanلاعند التمكين، لن يتم إعادة توجيه الدفع تلقائيًا بعد الانتهاء. بدلاً من ذلك، ستتلقى أحداث checkout.status و checkout.redirect_requested للتعامل مع إعادة التوجيه بنفسك.

​
الطرق

​
فتح الدفع

يفتح واجهة الدفع مع عنوان URL لجلسة الدفع المحدد. 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
يمكنك أيضًا تمرير خيارات إضافية لتخصيص سلوك الدفع: 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});
عند استخدام manualRedirect، تعامل مع إكمال الدفع في دالة رد النداء onEvent الخاصة بك: 
DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

​
إغلاق الدفع

يغلق overlay الدفع برمجيًا. 
DodoPayments.Checkout.close();

​
تحقق من الحالة

يعيد ما إذا كان overlay الدفع مفتوحًا حاليًا. 
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

​
الأحداث

يوفر SDK أحداثًا في الوقت الحقيقي يمكنك الاستماع إليها من خلال دالة رد النداء onEvent:

​
بيانات حدث حالة الدفع

عند تمكين manualRedirect، ستتلقى حدث checkout.status مع البيانات التالية: 
interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

​
بيانات حدث إعادة التوجيه المطلوبة للدفع

عند تمكين manualRedirect، ستتلقى حدث checkout.redirect_requested مع البيانات التالية: 
interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});
نوع الحدثالوصف
checkout.openedتم فتح overlay الدفع
checkout.payment_page_openedتم عرض صفحة الدفع
checkout.customer_details_submittedتم تقديم تفاصيل العميل والفوترة
checkout.closedتم إغلاق overlay الدفع
checkout.redirectسيقوم الدفع بإجراء إعادة توجيه
checkout.errorحدث خطأ أثناء الدفع
checkout.link_expiredتم إطلاقه عندما تنتهي جلسة الدفع. يتم استلامه فقط عندما يتم تعيين showTimer على false.
checkout.statusتم إطلاقه عندما يتم تمكين manualRedirect. يحتوي على حالة الدفع (succeeded، failed، أو processing).
checkout.redirect_requestedتم إطلاقه عندما يتم تمكين manualRedirect. يحتوي على عنوان URL لإعادة توجيه العميل إليه.

​
خيارات التنفيذ

​
تثبيت عبر مدير الحزم

قم بالتثبيت عبر npm أو yarn أو pnpm كما هو موضح في دليل التكامل خطوة بخطوة.

​
تنفيذ CDN

للتكامل السريع دون خطوة بناء، يمكنك استخدام CDN الخاص بنا: 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            displayType: "overlay",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

​
دعم TypeScript

تم كتابة SDK بلغة TypeScript ويشمل تعريفات نوع شاملة. جميع واجهات برمجة التطبيقات العامة مكتوبة بالكامل لتحسين تجربة المطور ودعم IntelliSense. 
import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

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

يوفر SDK معلومات تفصيلية عن الأخطاء من خلال نظام الأحداث. دائمًا قم بتنفيذ معالجة الأخطاء بشكل صحيح في دالة رد النداء onEvent الخاصة بك: 
DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});
دائمًا قم بمعالجة حدث checkout.error لتوفير تجربة مستخدم جيدة عند حدوث أخطاء.

​
أفضل الممارسات

  1. تهيئة مرة واحدة: قم بتهيئة SDK مرة واحدة عند تحميل تطبيقك، وليس في كل محاولة دفع
  2. معالجة الأخطاء: دائمًا قم بتنفيذ معالجة الأخطاء بشكل صحيح في دالة رد النداء الخاصة بك
  3. وضع الاختبار: استخدم وضع test أثناء التطوير وانتقل إلى live فقط عندما تكون جاهزًا للإنتاج
  4. معالجة الأحداث: تعامل مع جميع الأحداث ذات الصلة لتجربة مستخدم كاملة
  5. عناوين URL صالحة: استخدم دائمًا عناوين URL صالحة للدفع من واجهة برمجة التطبيقات لإنشاء جلسات الدفع
  6. TypeScript: استخدم TypeScript لتحسين أمان النوع وتجربة المطور
  7. حالات التحميل: عرض حالات التحميل أثناء فتح الدفع لتحسين تجربة المستخدم
  8. إعادة التوجيه اليدوية: استخدم manualRedirect عندما تحتاج إلى تحكم مخصص في التنقل بعد الدفع
  9. إدارة المؤقت: قم بتعطيل المؤقت (showTimer: false) إذا كنت ترغب في التعامل مع انتهاء الجلسة يدويًا

​
استكشاف الأخطاء وإصلاحها

الأسباب المحتملة:
  • لم يتم تهيئة SDK قبل استدعاء open()
  • عنوان URL للدفع غير صالح
  • أخطاء JavaScript في وحدة التحكم
  • مشاكل في الاتصال بالشبكة
الحلول:
  • تحقق من أن تهيئة SDK تحدث قبل فتح الدفع
  • تحقق من الأخطاء في وحدة التحكم
  • تأكد من أن عنوان URL للدفع صالح ومن واجهة برمجة التطبيقات لإنشاء جلسات الدفع
  • تحقق من الاتصال بالشبكة
الأسباب المحتملة:
  • لم يتم إعداد معالج الحدث بشكل صحيح
  • أخطاء JavaScript تمنع انتشار الحدث
  • لم يتم تهيئة SDK بشكل صحيح
الحلول:
  • تأكد من تكوين معالج الحدث بشكل صحيح في Initialize()
  • تحقق من وحدة التحكم في المتصفح بحثًا عن أخطاء JavaScript
  • تحقق من أن تهيئة SDK قد اكتملت بنجاح
  • اختبر مع معالج حدث بسيط أولاً
الأسباب المحتملة:
  • تعارضات CSS مع أنماط تطبيقك
  • إعدادات السمة لم يتم تطبيقها بشكل صحيح
  • مشاكل في التصميم المتجاوب
الحلول:
  • تحقق من تعارضات CSS في أدوات مطور المتصفح
  • تحقق من أن إعدادات السمة صحيحة
  • اختبر على أحجام شاشات مختلفة
  • تأكد من عدم وجود تعارضات في z-index مع overlay

​
تمكين Apple Pay

يسمح Apple Pay للعملاء بإكمال المدفوعات بسرعة وأمان باستخدام طرق الدفع المحفوظة لديهم. عند تمكينه، يمكن للعملاء فتح نافذة Apple Pay مباشرة من overlay الدفع على الأجهزة المدعومة.
يدعم Apple Pay على iOS 17+ و iPadOS 17+ و Safari 17+ على macOS.
لتمكين Apple Pay لنطاقك في الإنتاج، اتبع الخطوات التالية:
1

قم بتنزيل ورفع ملف ارتباط نطاق Apple Pay

قم بتنزيل ملف ارتباط نطاق Apple Pay.قم برفع الملف إلى خادم الويب الخاص بك في /.well-known/apple-developer-merchantid-domain-association. على سبيل المثال، إذا كان موقعك example.com، اجعل الملف متاحًا في https://example.com/well-known/apple-developer-merchantid-domain-association.
2

طلب تفعيل Apple Pay

أرسل بريدًا إلكترونيًا إلى [email protected] مع المعلومات التالية:
  • عنوان URL لنطاق الإنتاج الخاص بك (على سبيل المثال، https://example.com)
  • طلب لتمكين Apple Pay لنطاقك
ستتلقى تأكيدًا خلال 1-2 يوم عمل بمجرد تمكين Apple Pay لنطاقك.
3

تحقق من توفر Apple Pay

بعد تلقي التأكيد، اختبر Apple Pay في الدفع الخاص بك:
  1. افتح الدفع الخاص بك على جهاز مدعوم (iOS 17+ أو iPadOS 17+ أو Safari 17+ على macOS)
  2. تحقق من ظهور زر Apple Pay كخيار للدفع
  3. اختبر تدفق الدفع الكامل
يجب تمكين Apple Pay لنطاقك قبل أن يظهر كخيار للدفع في الإنتاج. اتصل بالدعم قبل الذهاب للعرض إذا كنت تخطط لتقديم Apple Pay.

​
دعم المتصفح

يدعم SDK دفع دودي المتصفحات التالية:
  • Chrome (الأحدث)
  • Firefox (الأحدث)
  • Safari (الأحدث)
  • Edge (الأحدث)
  • IE11+

​
الدفع المنبثق مقابل الدفع المدمج

اختر نوع الدفع المناسب لحالتك:
الميزةالدفع المنبثقالدفع المدمج
عمق التكاملنافذة منبثقة فوق الصفحةمدمج بالكامل في الصفحة
التحكم في التخطيطمحدودتحكم كامل
العلامة التجاريةمنفصل عن الصفحةسلس
جهد التنفيذأقلأعلى
الأفضل لـتكامل سريع، صفحات موجودةصفحات دفع مخصصة، تدفقات عالية التحويل
استخدم الدفع المنبثق للتكامل الأسرع مع تغييرات طفيفة على صفحاتك الحالية. استخدم الدفع المدمج عندما تريد أقصى تحكم في تجربة الدفع وعلامة تجارية سلسة.

​
الموارد ذات الصلة

الدفع المدمج

قم بتضمين الدفع مباشرة في صفحتك لتجارب متكاملة بالكامل.

واجهة برمجة التطبيقات لجلسات الدفع

أنشئ جلسات دفع لتشغيل تجارب الدفع الخاصة بك.

Webhooks

تعامل مع أحداث الدفع من جانب الخادم باستخدام webhooks.

دليل التكامل

دليل كامل لتكامل دودي للدفع.
للمزيد من المساعدة، قم بزيارة مجتمع Discord الخاص بنا أو اتصل بفريق دعم المطورين لدينا.