Overlay Checkout - Dodo Payments Documentation

نظرة عامة

يوفر Checkout SDK الخاص بـ Dodo Payments طريقة سلسة لدمج نافذة الدفع overlay الخاصة بنا في تطبيق الويب لديك. وقد بُني باستخدام TypeScript ومعايير الويب الحديثة، ويوفر حلاً موثوقًا لمعالجة المدفوعات، مع معالجة الأحداث في الوقت الفعلي وإمكانية تخصيص السمات.

عرض توضيحي

Interactive Demo

شاهد عملية الدفع overlay أثناء العمل من خلال العرض التوضيحي المباشر.

بدء سريع

ابدأ باستخدام Checkout SDK الخاص بـ Dodo Payments من خلال بضعة أسطر من التعليمات البرمجية فقط:

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 للدفع من create checkout session API.

دليل الدمج خطوة بخطوة

Install the SDK

ثبّت Checkout SDK الخاص بـ Dodo Payments باستخدام مدير الحزم المفضل لديك:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the 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 دائمًا قبل محاولة فتح عملية الدفع. يجب أن تحدث التهيئة مرة واحدة عند تحميل التطبيق.

Create a Checkout Button Component

أنشئ مكوّنًا يفتح نافذة الدفع overlay:

// 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>
  );
}

Add Checkout to Your Page

استخدم مكوّن زر الدفع في تطبيقك:

// 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>
  );
}

Handle Success and Failure Pages

أنشئ صفحات لمعالجة عمليات إعادة التوجيه الخاصة بالدفع:

// 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>
  );
}

Test Your Integration

شغّل خادم التطوير:

npm run dev

اختبر تدفق الدفع:
- انقر على زر الدفع
- تحقّق من ظهور النافذة overlay
- اختبر تدفق الدفع باستخدام بيانات اعتماد الاختبار
- أكّد عمل عمليات إعادة التوجيه بشكل صحيح

يجب أن ترى أحداث الدفع مسجّلة في وحدة تحكم المتصفح.

Go Live

عندما تصبح جاهزًا للإنتاج:

غيّر الوضع إلى 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

حدّث عناوين URL للدفع لاستخدام جلسات الدفع المباشرة من الواجهة الخلفية
اختبر التدفق الكامل في بيئة الإنتاج
راقب الأحداث والأخطاء

مرجع API

الإعدادات

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

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

الخيار	النوع	مطلوب	الوصف
`mode`	`"test" \| "live"`	نعم	وضع البيئة: `'test'` للتطوير، و`'live'` للإنتاج
`displayType`	`"overlay" \| "inline"`	لا	نوع العرض: `'overlay'` للدفع عبر نافذة modal (افتراضيًا)، و`'inline'` للدفع المضمّن
`onEvent`	`function`	نعم	دالة callback لمعالجة أحداث الدفع

خيارات الدفع

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}

الخيار	النوع	مطلوب	الوصف
`checkoutUrl`	`string`	نعم	عنوان URL لجلسة الدفع من create checkout session API
`options.showTimer`	`boolean`	لا	إظهار مؤقت الدفع أو إخفاؤه. القيمة الافتراضية هي `true`. عند تعطيله، ستتلقى حدث `checkout.link_expired` عند انتهاء الجلسة.
`options.showSecurityBadge`	`boolean`	لا	إظهار شارة الأمان أو إخفاؤها. القيمة الافتراضية هي `true`.

Methods

فتح عملية الدفع

يفتح نافذة الدفع overlay باستخدام عنوان 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,
  },
});

إغلاق عملية الدفع

يغلق نافذة الدفع overlay برمجيًا.

DodoPayments.Checkout.close();

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

يعيد ما إذا كانت نافذة الدفع overlay مفتوحة حاليًا.

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

الأحداث

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

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        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;
    }
  }
});

نوع الحدث	الوصف
`checkout.opened`	تم فتح نافذة الدفع overlay
`checkout.form_ready`	نموذج الدفع جاهز لاستقبال إدخال المستخدم. مفيد لإخفاء حالات التحميل.
`checkout.payment_page_opened`	تم عرض صفحة الدفع
`checkout.customer_details_submitted`	تم إرسال بيانات العميل والفوترة
`checkout.closed`	تم إغلاق نافذة الدفع overlay
`checkout.redirect`	سينفّذ الدفع عملية إعادة توجيه
`checkout.error`	حدث خطأ أثناء الدفع
`checkout.link_expired`	يُطلَق عند انتهاء جلسة الدفع. لا يتم تلقيه إلا عند ضبط `showTimer` على `false`.

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

التثبيت باستخدام مدير الحزم

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

التنفيذ عبر CDN

لإجراء دمج سريع من دون خطوة build، يمكنك استخدام 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 عند فتح الدفع. يدعم إعداد السمة الوضعين الفاتح والداكن، ما يتيح لك تخصيص الألوان والحدود والنصوص والأزرار ونصف قطر الحدود.

الخيار themeConfig من جانب العميل مهجور وسيُزال في الإصدار الرئيسي التالي من Checkout SDK (v2.0.0). يؤدي تمريره إلى تسجيل تحذير بشأن الإهمال في وحدة تحكم المتصفح. بدلاً من ذلك، قم بتهيئة المظهر عند إنشاء جلسة Checkout عبر API باستخدام المعامل customization.theme_config — راجع تخصيص مظهر Checkout — أو بصريًا من خلال صفحة التصميم في لوحة التحكم. تنطبق المظاهر المُهيأة للجلسة على Checkout overlay وinline وhosted على حد سواء.

يغطي هذا القسم تهيئة المظهر من جانب العميل المهجورة باستخدام Checkout SDK. النهج الموصى به هو تهيئة المظاهر من جانب الخادم عند إنشاء جلسة Checkout عبر API باستخدام المعامل theme_config. راجع تخصيص مظهر Checkout للتهيئة على مستوى API، أو استخدم صفحة التصميم في لوحة التحكم لتهيئة المظاهر بصريًا مع معاينة مباشرة.

تهيئة المظهر الأساسية

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",
    },
  },
});

تجاوز جزئي للمظهر

يمكنك تجاوز خصائص محددة فقط. سيستخدم Checkout القيم الافتراضية للخصائص التي لا تحددها:

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
    },
  },
});

تهيئة المظهر مع الخيارات الأخرى

يمكنك دمج تهيئة المظهر مع خيارات Checkout الأخرى:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    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 لتوفير تجربة مستخدم جيدة عند حدوث الأخطاء.

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

التهيئة مرة واحدة: قم بتهيئة SDK مرة واحدة عند تحميل تطبيقك، وليس عند كل محاولة Checkout
معالجة الأخطاء: احرص دائمًا على تنفيذ معالجة مناسبة للأخطاء في استدعاء الأحداث
وضع الاختبار: استخدم وضع test أثناء التطوير، وانتقل إلى live فقط عند الاستعداد للإنتاج
معالجة الأحداث: عالج جميع الأحداث ذات الصلة لتوفير تجربة مستخدم متكاملة
عناوين URL صالحة: استخدم دائمًا عناوين Checkout URL صالحة من API إنشاء جلسة Checkout
TypeScript: استخدم TypeScript لتحسين أمان الأنواع وتجربة المطور
حالات التحميل: اعرض حالات التحميل أثناء فتح Checkout لتحسين تجربة المستخدم
إدارة المؤقت: عطّل المؤقت (showTimer: false) إذا كنت تريد إدارة انتهاء صلاحية الجلسة يدويًا

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

Checkout not opening

الأسباب المحتملة:

لم تتم تهيئة SDK قبل استدعاء open()
عنوان Checkout URL غير صالح
أخطاء JavaScript في وحدة التحكم
مشكلات في اتصال الشبكة

الحلول:

تحقق من حدوث تهيئة SDK قبل فتح Checkout
تحقق من وجود أخطاء في وحدة التحكم
تأكد من أن عنوان Checkout URL صالح ومن API إنشاء جلسة Checkout
تحقق من اتصال الشبكة

Events not firing

الأسباب المحتملة:

لم تتم تهيئة معالج الأحداث بشكل صحيح
أخطاء JavaScript تمنع انتشار الأحداث
لم تتم تهيئة SDK بشكل صحيح

الحلول:

تأكد من تهيئة معالج الأحداث بشكل صحيح في Initialize()
تحقق من وحدة تحكم المتصفح بحثًا عن أخطاء JavaScript
تحقق من اكتمال تهيئة SDK بنجاح
اختبر أولًا باستخدام معالج أحداث بسيط

Styling issues

الأسباب المحتملة:

تعارضات CSS مع أنماط تطبيقك
لم يتم تطبيق إعدادات المظهر بشكل صحيح
مشكلات في التصميم المتجاوب

الحلول:

تحقق من تعارضات CSS في أدوات مطوري المتصفح
تحقق من صحة إعدادات المظهر
اختبر على أحجام شاشات مختلفة
تأكد من عدم وجود تعارضات في z-index مع overlay

تفعيل المحافظ الرقمية

للحصول على معلومات مفصلة حول إعداد Google Pay والمحافظ الرقمية الأخرى، راجع صفحة المحافظ الرقمية.

لا يدعم Checkout overlay Apple Pay حتى الآن. سيأتي دعم Apple Pay قريبًا.

دعم المتصفحات

يدعم Checkout SDK الخاص بـ Dodo Payments المتصفحات التالية:

Chrome (أحدث إصدار)
Firefox (أحدث إصدار)
Safari (أحدث إصدار)
Edge (أحدث إصدار)
IE11+

Checkout overlay مقابل Checkout inline

اختر نوع Checkout المناسب لحالة الاستخدام الخاصة بك:

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

استخدم Checkout overlay لتكامل أسرع مع إجراء تغييرات محدودة على صفحاتك الحالية. استخدم Checkout inline عندما تريد أقصى قدر من التحكم في تجربة Checkout وعلامة تجارية متكاملة بسلاسة.

موارد ذات صلة

Inline Checkout

ضمّن Checkout مباشرةً في صفحتك للحصول على تجارب متكاملة بالكامل.

Checkout Sessions API

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

Webhooks

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

Integration Guide

دليل كامل لدمج Dodo Payments.

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

​نظرة عامة

​عرض توضيحي

Interactive Demo

​بدء سريع

​دليل الدمج خطوة بخطوة

​مرجع API

​الإعدادات

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

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

​Methods

​فتح عملية الدفع

​إغلاق عملية الدفع

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

​الأحداث

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

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

​التنفيذ عبر CDN

​تخصيص السمة

​تهيئة المظهر الأساسية

​تهيئة المظهر الكاملة

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

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

​تجاوز جزئي للمظهر

​تهيئة المظهر مع الخيارات الأخرى

​أنواع TypeScript

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

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

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

​تفعيل المحافظ الرقمية

​دعم المتصفحات

​Checkout overlay مقابل Checkout inline

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

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

نظرة عامة

عرض توضيحي

بدء سريع

دليل الدمج خطوة بخطوة

مرجع API

الإعدادات

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

خيارات الدفع

Methods

فتح عملية الدفع

إغلاق عملية الدفع

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

الأحداث

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

التثبيت باستخدام مدير الحزم

التنفيذ عبر CDN

تخصيص السمة

تهيئة المظهر الأساسية

تهيئة المظهر الكاملة

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

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

تجاوز جزئي للمظهر

تهيئة المظهر مع الخيارات الأخرى

أنواع TypeScript

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

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

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

تفعيل المحافظ الرقمية

دعم المتصفحات

Checkout overlay مقابل Checkout inline

موارد ذات صلة