Overlay Checkout

يفتح overlay checkout نافذة منبثقة فوق صفحتك. يُدخل العملاء تفاصيل الدفع الخاصة بهم في النافذة المنبثقة بينما تظل صفحتك ظاهرة في الخلفية. عند إغلاقهم للنافذة المنبثقة، تعود السيطرة إلى صفحتك. وعند إكمال الدفع، تتم إعادة توجيههم إلى return_url.

نافذة الدفع المنبثقة معروضة فوق صفحة منتج

Interactive Demo

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

البدء السريع

ثبّت SDK، ثم هيّئه وافتح صفحة الدفع باستخدام عنوان checkout URL من create checkout session API:

import { DodoPayments } from "dodopayments-checkout";

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

التكامل خطوة بخطوة

Install the SDK

ثبّت الحزمة باستخدام npm أو yarn أو pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

استدعِ Initialize مرة واحدة عند تحميل تطبيقك، وعادةً ما يكون ذلك في المكوّن الرئيسي أو نقطة دخول التطبيق:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

هيّئ SDK دائمًا قبل فتح صفحة الدفع. هيّئه مرة واحدة عند تحميل تطبيقك، وليس قبل كل محاولة دفع.

Create a Checkout Button

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

// 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(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.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 the Button 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 Redirects

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

// 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

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

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

Go Live

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

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

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

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

مرجع API

التهيئة

استدعِ Initialize مرة واحدة لإعداد SDK:

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

DodoPayments.Initialize(options);

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

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

افتح نافذة الدفع المنبثقة:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

الخيار	النوع	مطلوب	الوصف
`checkoutUrl`	`string`	نعم	عنوان URL لجلسة الدفع من create checkout session API
`options.showTimer`	`boolean`	لا	إظهار مؤقت الجلسة أو إخفاؤه. القيمة الافتراضية هي `true`. عند تعطيله، تتلقى حدث `checkout.link_expired` عند انتهاء الجلسة.
`options.showSecurityBadge`	`boolean`	لا	إظهار شارة الأمان أو إخفاؤها. القيمة الافتراضية هي `true`
`options.manualRedirect`	`boolean`	لا	عند ضبطه على `true`، يمنع عمليات إعادة التوجيه التلقائية. يصدر Checkout الحدث `checkout.status` مع نتيجة الدفع، والحدث `checkout.redirect_requested` مع عنوان URL المراد فتحه، وتتولى أنت عملية التنقل
`options.themeConfig`	`ThemeConfig`	لا	مهمل. اضبط السمة من جهة الخادم عند إنشاء جلسة الدفع بدلًا من ذلك
`options.payButtonText`	`string`	لا	نص مخصص لزر الدفع
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	لا	حجم الخط العام لصفحة الدفع
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	لا	وزن الخط العام لصفحة الدفع

إغلاق صفحة الدفع

أغلق النافذة المنبثقة برمجيًا:

DodoPayments.Checkout.close();

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

تحقّق مما إذا كانت النافذة المنبثقة مفتوحة حاليًا:

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

الأحداث

استمع إلى أحداث الدفع عبر callback‏ onEvent المُمرَّر إلى Initialize:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

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

تنفيذ CDN

للتكامل السريع دون خطوة build، حمّل SDK من 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>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      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://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

تخصيص السمة

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

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

إذا كان لا بد من استخدام إعداد السمة من جهة العميل، فمرّر themeConfig في المعامل options:

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

خصائص السمة

جميع خصائص السمة المتاحة للوضعين الفاتح والداكن:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

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

طبّق دائمًا معالجة الأخطاء في callback‏ onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

تعامل دائمًا مع الحدث checkout.error لتوفير تجربة مستخدم جيدة عند حدوث الأخطاء.

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

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

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

Events not firing

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

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

الحلول:

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

Styling issues

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

تعارض CSS مع أنماط تطبيقك
لم تُطبَّق إعدادات السمة بشكل صحيح
مشكلات في التصميم المتجاوب

الحلول:

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

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

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

لا يتوفر Apple Pay بعد في overlay checkout.

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

يدعم Checkout SDK الخاص بـ Dodo Payments ما يلي:

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

مقارنة Overlay Checkout وInline Checkout

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

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

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

موارد ذات صلة

Inline Checkout

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

Checkout Sessions API

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

Webhooks

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

Integration Guide

دليل شامل لتكامل Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

البدء السريع

التكامل خطوة بخطوة

مرجع API

التهيئة

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

إغلاق صفحة الدفع

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

الأحداث

تنفيذ CDN

تخصيص السمة

خصائص السمة

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

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

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

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

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

مقارنة Overlay Checkout وInline Checkout

موارد ذات صلة

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​البدء السريع

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

​مرجع API

​التهيئة

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

​إغلاق صفحة الدفع

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

​الأحداث

​تنفيذ CDN

​تخصيص السمة

​خصائص السمة

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

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

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

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

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

​مقارنة Overlay Checkout وInline Checkout

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

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

البدء السريع

التكامل خطوة بخطوة

مرجع API

التهيئة

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

إغلاق صفحة الدفع

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

الأحداث

تنفيذ CDN

تخصيص السمة

خصائص السمة

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

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

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

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

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

مقارنة Overlay Checkout وInline Checkout

موارد ذات صلة