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

نظرة عامة

تتيح لك عملية الدفع المباشر إنشاء تجارب دفع متكاملة تمامًا تتمازج بسلاسة مع موقعك الإلكتروني أو تطبيقك. على عكس الدفع المنبثق، الذي يفتح كنافذة منبثقة فوق صفحتك، يقوم الدفع المباشر بتضمين نموذج الدفع مباشرة في تخطيط صفحتك. باستخدام الدفع المباشر، يمكنك:
  • إنشاء تجارب دفع متكاملة تمامًا مع تطبيقك أو موقعك الإلكتروني
  • السماح لـ Dodo Payments بالتقاط معلومات العملاء والدفع بشكل آمن في إطار دفع محسن
  • عرض العناصر، والمجموعات، ومعلومات أخرى من Dodo Payments على صفحتك
  • استخدام طرق وأحداث SDK لبناء تجارب دفع متقدمة
صورة غلاف الدفع المباشر

كيف يعمل

يعمل الدفع المباشر عن طريق تضمين إطار Dodo Payments الآمن في موقعك الإلكتروني أو تطبيقك. يتولى إطار الدفع جمع معلومات العملاء والتقاط تفاصيل الدفع. تعرض صفحتك قائمة العناصر، والمجموعات، والخيارات لتغيير ما هو موجود في عملية الدفع. يسمح لك SDK بتفاعل صفحتك مع إطار الدفع. تقوم Dodo Payments تلقائيًا بإنشاء اشتراك عند اكتمال عملية الدفع، جاهزًا للتوفير.
يتولى إطار الدفع المباشر التعامل بشكل آمن مع جميع معلومات الدفع الحساسة، مما يضمن الامتثال لمعايير PCI دون الحاجة إلى شهادة إضافية من جانبك.

ما الذي يجعل الدفع المباشر جيدًا؟

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

مثال على تخطيط الدفع المباشر يظهر العناصر المطلوبة

  1. معلومات متكررة: إذا كانت متكررة، كم مرة تتكرر والمبلغ المطلوب دفعه عند التجديد. إذا كانت تجربة مجانية، كم من الوقت تستمر التجربة.
  2. وصف العناصر: وصف لما يتم شراؤه.
  3. مجموع المعاملات: مجموع المعاملات، بما في ذلك المجموع الفرعي، والضرائب الإجمالية، والمجموع الكلي. تأكد من تضمين العملة أيضًا.
  4. تذييل Dodo Payments: إطار الدفع المباشر الكامل، بما في ذلك تذييل الدفع الذي يحتوي على معلومات حول Dodo Payments، وشروط البيع، وسياسة الخصوصية الخاصة بنا.
  5. سياسة الاسترداد: رابط إلى سياسة الاسترداد الخاصة بك، إذا كانت تختلف عن سياسة الاسترداد القياسية لـ Dodo Payments.
قم دائمًا بعرض إطار الدفع المباشر الكامل، بما في ذلك التذييل. إزالة أو إخفاء المعلومات القانونية ينتهك متطلبات الامتثال.

رحلة العميل

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

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

يمكنك فتح الدفع الفوري عن طريق تمرير العناصر أو معاملة موجودة. استخدم SDK لعرض وتحديث المعلومات على الصفحة، وطرق SDK لتحديث العناصر بناءً على تفاعل العميل.الصفحة الأولية للدفع مع قائمة العناصر ونموذج الدفع
2

يدخل العميل تفاصيله

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

يختار العميل طريقة الدفع

بعد إدخال تفاصيلهم، يتم تقديم طرق الدفع المتاحة للعملاء ونموذج الدفع. قد تشمل الخيارات بطاقة ائتمان أو بطاقة خصم، PayPal، Apple Pay، Google Pay، وطرق دفع محلية أخرى بناءً على موقعهم.عرض طرق الدفع المحفوظة إذا كانت متاحة لتسريع عملية الدفع.طرق الدفع المتاحة ونموذج تفاصيل البطاقة
4

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

تقوم Dodo Payments بتوجيه كل عملية دفع إلى أفضل جهة إصدار لتلك المعاملة للحصول على أفضل فرصة للنجاح. يدخل العملاء في سير عمل النجاح الذي يمكنك بناؤه.شاشة النجاح مع علامة تأكيد
5

Dodo Payments تنشئ اشتراكًا

تقوم Dodo Payments تلقائيًا بإنشاء اشتراك للعميل، جاهزًا للتوفير. يتم الاحتفاظ بطريقة الدفع التي استخدمها العميل في السجل للتجديدات أو تغييرات الاشتراك.تم إنشاء الاشتراك مع إشعار webhook

البداية السريعة

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

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});
تأكد من وجود عنصر حاوية مع id المقابل على صفحتك: <div id="dodo-inline-checkout"></div>.

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

1

تثبيت SDK

قم بتثبيت SDK الدفع من Dodo Payments:
npm install dodopayments-checkout
2

تهيئة SDK لعرض الدفع الفوري

قم بتهيئة SDK وحدد displayType: 'inline'. يجب عليك أيضًا الاستماع لحدث checkout.breakdown لتحديث واجهة المستخدم الخاصة بك بحسابات الضرائب والإجماليات في الوقت الحقيقي.
import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});
3

إنشاء عنصر حاوية

أضف عنصرًا إلى HTML الخاص بك حيث سيتم حقن إطار الدفع:
<div id="dodo-inline-checkout"></div>
4

فتح الدفع

استدعاء DodoPayments.Checkout.open() مع checkoutUrl و elementId من الحاوية الخاصة بك:
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});
5

اختبر تكاملك

  1. ابدأ خادم التطوير الخاص بك:
npm run dev
  1. اختبر تدفق الدفع:
    • أدخل تفاصيل بريدك الإلكتروني والعنوان في الإطار الفوري.
    • تحقق من أن ملخص الطلب المخصص الخاص بك يتم تحديثه في الوقت الحقيقي.
    • اختبر تدفق الدفع باستخدام بيانات اعتماد الاختبار.
    • تأكد من أن عمليات إعادة التوجيه تعمل بشكل صحيح.
يجب أن ترى أحداث checkout.breakdown مسجلة في وحدة تحكم المتصفح الخاصة بك إذا قمت بإضافة سجل وحدة تحكم في رد الاتصال onEvent.
6

اذهب للعيش

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

مثال كامل على React

هذا المثال يوضح كيفية تنفيذ ملخص طلب مخصص بجانب الدفع الفوري، مع الحفاظ على تزامنهم باستخدام حدث checkout.breakdown.
"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

مرجع API

التكوين

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

interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}
الخيارالنوعمطلوبالوصف
mode"test" | "live"نعموضع البيئة.
displayType"inline" | "overlay"نعميجب تعيينه إلى "inline" لتضمين الدفع.
onEventfunctionنعمدالة رد الاتصال لمعالجة أحداث الدفع.

خيارات الدفع

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

الطرق

فتح الدفع

يفتح إطار الدفع في الحاوية المحددة.
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});
يمكنك أيضًا تمرير خيارات إضافية لتخصيص سلوك الدفع:
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
    payButtonText: "Pay Now",
  },
});
عند استخدام manualRedirect، تعامل مع إكمال الدفع في رد الاتصال onEvent الخاص بك:
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  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
    }
  },
});

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

يتم إزالة إطار الدفع برمجيًا وتنظيف مستمعي الأحداث.
DodoPayments.Checkout.close();

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

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

الأحداث

يوفر SDK أحداثًا في الوقت الحقيقي من خلال رد الاتصال onEvent. بالنسبة للدفع المضمن، فإن checkout.breakdown مفيد بشكل خاص لمزامنة واجهة المستخدم الخاصة بك.
نوع الحدثالوصف
checkout.openedتم تحميل إطار الدفع.
checkout.breakdownتم إطلاقه عند تحديث الأسعار أو الضرائب أو الخصومات.
checkout.customer_details_submittedتم تقديم تفاصيل العميل.
checkout.redirectستقوم عملية الدفع بإجراء إعادة توجيه (على سبيل المثال، إلى صفحة البنك).
checkout.errorحدث خطأ أثناء عملية الدفع.
checkout.link_expiredتم إطلاقه عند انتهاء جلسة الدفع. يتم استلامه فقط عندما يتم تعيين showTimer إلى false.
checkout.statusتم إطلاقه عند تمكين manualRedirect. يحتوي على حالة الدفع (succeeded، failed، أو processing).
checkout.redirect_requestedتم إطلاقه عند تمكين manualRedirect. يحتوي على عنوان URL لإعادة توجيه العميل إليه.

بيانات تفصيل عملية الدفع

يوفر حدث checkout.breakdown البيانات التالية:
interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

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

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

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

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

فهم حدث التفصيل

يعد حدث checkout.breakdown الطريقة الأساسية لمزامنة واجهة المستخدم الخاصة بتطبيقك مع حالة دفع Dodo Payments. عندما يتم إطلاقه:
  • عند التهيئة: مباشرة بعد تحميل إطار الدفع واستعداده.
  • عند تغيير العنوان: كلما اختار العميل دولة أو أدخل رمزًا بريديًا يؤدي إلى إعادة حساب الضرائب.
تفاصيل الحقول:
الحقلالوصف
subTotalمجموع جميع العناصر في الجلسة قبل تطبيق أي خصومات أو ضرائب.
discountالقيمة الإجمالية لجميع الخصومات المطبقة.
taxمبلغ الضريبة المحسوب. في وضع inline، يتم تحديثه ديناميكيًا أثناء تفاعل المستخدم مع حقول العنوان.
totalالنتيجة الرياضية لـ subTotal - discount + tax في العملة الأساسية للجلسة.
currencyرمز العملة ISO (مثل "USD") لقيم المجموع الفرعي القياسية والخصم والضريبة.
finalTotalالمبلغ الفعلي الذي يتم تحصيله من العميل. قد يتضمن ذلك تعديلات إضافية على سعر الصرف أو رسوم طرق الدفع المحلية التي ليست جزءًا من تفصيل السعر الأساسي.
finalTotalCurrencyالعملة التي يدفع بها العميل فعليًا. قد تختلف هذه عن currency إذا كانت القدرة الشرائية أو تحويل العملة المحلية نشطة.
نصائح تكامل رئيسية:
  1. تنسيق العملة: يتم دائمًا إرجاع الأسعار كأعداد صحيحة في أصغر وحدة عملة (مثل السنتات للدولار الأمريكي، والين لليابان). لعرضها، قسمها على 100 (أو القوة المناسبة لـ 10) أو استخدم مكتبة تنسيق مثل Intl.NumberFormat.
  2. التعامل مع الحالات الأولية: عند تحميل عملية الدفع لأول مرة، قد تكون tax و discount إما 0 أو null حتى يقدم المستخدم معلومات الفوترة الخاصة به أو يطبق رمزًا. يجب أن تتعامل واجهة المستخدم الخاصة بك مع هذه الحالات بشكل جيد (مثل عرض شرطة أو إخفاء الصف).
  3. “الإجمالي النهائي” مقابل “الإجمالي”: بينما يعطيك total حساب السعر القياسي، فإن finalTotal هو مصدر الحقيقة للمعاملة. إذا كان finalTotal موجودًا، فإنه يعكس بالضبط ما سيتم تحصيله من بطاقة العميل، بما في ذلك أي تعديلات ديناميكية.
  4. التعليقات في الوقت الحقيقي: استخدم حقل tax لإظهار للمستخدمين أن الضرائب يتم حسابها في الوقت الحقيقي. يوفر هذا شعورًا “حيًا” لصفحة الدفع الخاصة بك ويقلل من الاحتكاك أثناء خطوة إدخال العنوان.

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

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

قم بالتثبيت عبر 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 Inline 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",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </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
        inputFocusBorder: "#D0D5DD", // Input focus 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",
        inputFocusBorder: "#323232",
        
        // 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: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});
تأكد دائمًا من التعامل مع حدث checkout.error لتوفير تجربة مستخدم جيدة عند حدوث مشكلات.

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

  1. تصميم متجاوب: تأكد من أن عنصر الحاوية لديك يحتوي على عرض وارتفاع كافيين. عادةً ما يتمدد iframe لملء حاويته.
  2. التزامن: استخدم حدث checkout.breakdown للحفاظ على تزامن ملخص الطلب المخصص أو جداول الأسعار مع ما يراه المستخدم في إطار الدفع.
  3. حالات التحميل: اعرض مؤشر تحميل في حاويتك حتى يتم إطلاق حدث checkout.opened.
  4. التنظيف: استدعِ DodoPayments.Checkout.close() عند تفكيك مكونك لتنظيف iframe ومستمعي الأحداث.
بالنسبة لتنفيذات الوضع الداكن، يُوصى باستخدام #0d0d0d كلون خلفية لتحقيق تكامل بصري مثالي مع إطار الدفع المضمن.

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

  • تحقق من أن elementId يتطابق مع id لــ div الذي يوجد فعليًا في DOM.
  • تأكد من تمرير displayType: 'inline' إلى Initialize.
  • تحقق من أن checkoutUrl صالح.
  • تأكد من أنك تستمع لحدث checkout.breakdown.
  • يتم حساب الضرائب فقط بعد أن يدخل المستخدم دولة ورمز بريدي صالحين في إطار الدفع.

تفعيل 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

أرسل بريدًا إلكترونيًا إلى [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 دفع Dodo Payments المتصفحات التالية:
  • Chrome (الأحدث)
  • Firefox (الأحدث)
  • Safari (الأحدث)
  • Edge (الأحدث)
  • IE11+

الدفع المضمن مقابل الدفع المنبثق

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

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

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