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

نظرة عامة

يوفر 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تم فتح واجهة الدفع
checkout.payment_page_openedتم عرض صفحة الدفع
checkout.customer_details_submittedتم تقديم تفاصيل العميل والفوترة
checkout.closedتم إغلاق واجهة الدفع
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>

تخصيص السمة

يمكنك تخصيص مظهر الدفع عن طريق تمرير كائن themeConfig في معلمة options عند فتح الدفع. يدعم تكوين السمة كلا من الوضعين الفاتح والداكن، مما يتيح لك تخصيص الألوان، الحدود، النصوص، الأزرار، ونصف قطر الحدود.

تكوين السمة الأساسية

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

تكوين السمة الكامل

جميع خصائص السمة المتاحة:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

الوضع الفاتح فقط

إذا كنت ترغب فقط في تخصيص السمة الفاتحة:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

الوضع الداكن فقط

إذا كنت ترغب فقط في تخصيص السمة الداكنة:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

تجاوز جزئي للسمة

يمكنك تجاوز خصائص معينة فقط. ستستخدم صفحة الدفع القيم الافتراضية للخصائص التي لا تحددها:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

تكوين السمة مع خيارات أخرى

يمكنك دمج تكوين السمة مع خيارات الدفع الأخرى:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

أنواع TypeScript

لمستخدمي TypeScript، يتم تصدير جميع أنواع تكوين السمة:
import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

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

يوفر 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 مع الطبقة

تمكين Apple Pay

يسمح Apple Pay للعملاء بإكمال المدفوعات بسرعة وأمان باستخدام طرق الدفع المحفوظة لديهم. عند تمكينه، يمكن للعملاء فتح نافذة Apple Pay مباشرة من طبقة الدفع على الأجهزة المدعومة.
يدعم 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

أرسل بريدًا إلكترونيًا إلى support@dodopayments.com مع المعلومات التالية:
  • عنوان 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 لمدفوعات Dodo المتصفحات التالية: