الدفع الفوري

نظرة عامة

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

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

كيف يعمل

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

يتولى إطار الدفع المباشر التعامل بشكل آمن مع جميع معلومات الدفع الحساسة، مما يضمن الامتثال لمعايير PCI دون الحاجة إلى شهادة إضافية من جانبك.

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

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

مثال على الدفع المباشر مع العناصر المطلوبة موضحة

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

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

قم دائمًا بعرض إطار الدفع المباشر الكامل، بما في ذلك التذييل. إزالة أو إخفاء المعلومات القانونية ينتهك متطلبات الامتثال.

رحلة العميل

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

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

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

الصفحة الأولية للدفع مع قائمة العناصر ونموذج الدفع

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

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

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

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

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

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

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

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

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

ابدأ مع الدفع الفوري من 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>.

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

تثبيت SDK

قم بتثبيت SDK الدفع من Dodo Payments:

npm install dodopayments-checkout

تهيئة 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.
    }
  },
});

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

أضف عنصرًا إلى HTML الخاص بك حيث سيتم حقن إطار الدفع:

<div id="dodo-inline-checkout"></div>

فتح الدفع

استدعاء DodoPayments.Checkout.open() مع checkoutUrl و elementId من الحاوية الخاصة بك:

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

اختبر تكاملك

ابدأ خادم التطوير الخاص بك:

npm run dev

اختبر تدفق الدفع:
- أدخل تفاصيل بريدك الإلكتروني والعنوان في الإطار الفوري.
- تحقق من أن ملخص الطلب المخصص الخاص بك يتم تحديثه في الوقت الحقيقي.
- اختبر تدفق الدفع باستخدام بيانات اعتماد الاختبار.
- تأكد من أن عمليات إعادة التوجيه تعمل بشكل صحيح.

يجب أن ترى أحداث checkout.breakdown مسجلة في وحدة تحكم المتصفح الخاصة بك إذا قمت بإضافة سجل وحدة تحكم في رد الاتصال onEvent.

اذهب للعيش

عندما تكون جاهزًا للإنتاج:

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

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

قم بتحديث عناوين URL للدفع الخاصة بك لاستخدام جلسات الدفع الحية من الخلفية الخاصة بك.
اختبر التدفق الكامل في الإنتاج.

مثال كامل على 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"` لتضمين الدفع.
`onEvent`	`function`	نعم	دالة رد الاتصال لمعالجة أحداث الدفع.

خيارات الدفع

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
}

الخيار	النوع	مطلوب	الوصف
`checkoutUrl`	`string`	نعم	عنوان URL لجلسة الدفع.
`elementId`	`string`	نعم	`id` لعنصر DOM حيث يجب عرض الدفع.

الطرق

فتح الدفع

يفتح إطار الدفع في الحاوية المحددة.

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

إغلاق الدفع

يزيل إطار الدفع برمجيًا وينظف مستمعي الأحداث.

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.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
}

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

يعد حدث checkout.breakdown الطريقة الأساسية للحفاظ على واجهة المستخدم الخاصة بتطبيقك متزامنة مع حالة دفع Dodo Payments. عندما يتم إطلاقه:

عند التهيئة: مباشرة بعد تحميل إطار الدفع واستعداده.
عند تغيير العنوان: كلما اختار العميل دولة أو أدخل رمزًا بريديًا يؤدي إلى إعادة حساب الضرائب.

تفاصيل الحقول:

الحقل	الوصف
`subTotal`	مجموع جميع العناصر في الجلسة قبل تطبيق أي خصومات أو ضرائب.
`discount`	القيمة الإجمالية لجميع الخصومات المطبقة.
`tax`	مبلغ الضريبة المحسوب. في وضع `inline`، يتم تحديث هذا ديناميكيًا أثناء تفاعل المستخدم مع حقول العنوان.
`total`	النتيجة الرياضية لـ `subTotal - discount + tax` في العملة الأساسية للجلسة.
`currency`	رمز العملة ISO (على سبيل المثال، `"USD"`) للقيم القياسية للفرعية والخصم والضرائب.
`finalTotal`	المبلغ الفعلي الذي يتم تحصيله من العميل. قد يتضمن ذلك تعديلات إضافية على سعر الصرف أو رسوم طريقة الدفع المحلية التي ليست جزءًا من تحليل السعر الأساسي.
`finalTotalCurrency`	العملة التي يدفع بها العميل فعليًا. قد تختلف هذه عن `currency` إذا كانت القدرة الشرائية أو تحويل العملة المحلية نشطة.

نصائح تكامل رئيسية:

تنسيق العملة: يتم دائمًا إرجاع الأسعار كأعداد صحيحة في أصغر وحدة عملة (على سبيل المثال، السنتات للدولار الأمريكي، والين للياباني). لعرضها، قسمها على 100 (أو القوة المناسبة لـ 10) أو استخدم مكتبة تنسيق مثل Intl.NumberFormat.
معالجة الحالات الأولية: عند تحميل الدفع لأول مرة، قد تكون tax و discount إما 0 أو null حتى يقدم المستخدم معلومات الفوترة الخاصة به أو يطبق رمزًا. يجب أن تتعامل واجهة المستخدم الخاصة بك مع هذه الحالات بشكل جيد (على سبيل المثال، عرض شرطة — أو إخفاء الصف).
“الإجمالي النهائي” مقابل “الإجمالي”: بينما يعطيك total حساب السعر القياسي، فإن finalTotal هو مصدر الحقيقة للمعاملة. إذا كان finalTotal موجودًا، فإنه يعكس بالضبط ما سيتم تحصيله من بطاقة العميل، بما في ذلك أي تعديلات ديناميكية.
التعليقات في الوقت الحقيقي: استخدم حقل 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>

دعم TypeScript

تم كتابة SDK بلغة TypeScript ويشمل تعريفات نوع شاملة.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

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

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

يوفر 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 لتوفير تجربة مستخدم جيدة عند حدوث مشكلات.

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

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

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

إطار الدفع لا يظهر

تحقق من أن elementId يتطابق مع id ل div الذي يوجد بالفعل في DOM.
تأكد من أنه تم تمرير displayType: 'inline' إلى Initialize.
تحقق من أن checkoutUrl صالح.

الضرائب لا تتحدث في واجهتي

تأكد من أنك تستمع لحدث checkout.breakdown.
يتم حساب الضرائب فقط بعد أن يدخل المستخدم دولة ورمزًا بريديًا صالحين في إطار الدفع.

دعم المتصفح

يدعم SDK الدفع من Dodo Payments المتصفحات التالية:

Chrome (الأحدث)
Firefox (الأحدث)
Safari (الأحدث)
Edge (الأحدث)
IE11+

Apple Pay غير مدعوم حاليًا في تجربة الدفع الفوري. نخطط لإضافة دعم لـ Apple Pay في إصدار مستقبلي.