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

Overview

Inline checkout lets you create fully integrated checkout experiences that blend seamlessly with your website or application. Unlike the overlay checkout, which opens as a modal on top of your page, inline checkout embeds the payment form directly into your page layout. Using inline checkout, you can:
  • Create checkout experiences that are fully integrated with your app or website
  • Let Dodo Payments securely capture customer and payment information in an optimized checkout frame
  • Display items, totals, and other information from Dodo Payments on your page
  • Use SDK methods and events to build advanced checkout experiences
صورة غلاف الدفع المضمن

How It Works

Inline checkout works by embedding a secure Dodo Payments frame into your website or app. The checkout frame handles collecting customer information and capturing payment details. Your page displays the items list, totals, and options for changing what’s on the checkout. The SDK lets your page and the checkout frame interact with each other. Dodo Payments automatically creates a subscription when a checkout completes, ready for you to provision.
The inline checkout frame securely handles all sensitive payment information, ensuring PCI compliance without additional certification on your end.

What Makes a Good Inline Checkout?

It’s important that customers know who they’re buying from, what they’re buying, and how much they’re paying. To build an inline checkout that’s compliant and optimized for conversion, your implementation must include:
مثال على الدفع المضمن مع العناصر المطلوبة محددة
  1. Recurring information: If recurring, how often it recurs and the total to pay on renewal. If a trial, how long the trial lasts.
  2. Item descriptions: A description of what’s being purchased.
  3. Transaction totals: Transaction totals, including subtotal, total tax, and grand total. Be sure to include the currency too.
  4. Dodo Payments footer: The full inline checkout frame, including the checkout footer that has information about Dodo Payments, our terms of sale, and our privacy policy.
  5. Refund policy: A link to your refund policy, if it differs from the Dodo Payments standard refund policy.
Always display the complete inline checkout frame, including the footer. Removing or hiding legal information violates compliance requirements.

Customer Journey

The checkout flow is determined by your checkout session configuration. Depending on how you configure the checkout session, customers will experience a checkout that may present all information on a single page or across multiple steps.
1

Customer opens checkout

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

Customer enters their details

Inline checkout first asks customers to enter their email address, select their country, and (where required) enter their ZIP or postal code. This step gathers all necessary information to determine taxes and available payment options.You can prefill customer details and present saved addresses to streamline the experience.
3

Customer selects payment method

After entering their details, customers are presented with available payment methods and the payment form. Options may include credit or debit card, PayPal, Apple Pay, Google Pay, and other local payment methods based on their location.Display saved payment methods if available to speed up checkout.طرق الدفع المتاحة ونموذج تفاصيل البطاقة
4

Checkout completed

Dodo Payments routes every payment to the best acquirer for that sale to get the best possible chance of success. Customers enter a success workflow that you can build.شاشة النجاح بعلامة التحقق
5

Dodo Payments creates subscription

Dodo Payments automatically creates a subscription for the customer, ready for you to provision. The payment method the customer used is held on file for renewals or subscription changes.تم إنشاء الاشتراك مع إشعار webhook

Quick Start

Get started with the Dodo Payments Inline Checkout in just a few lines of code:
Ensure you have a container element with the corresponding id on your page: <div id="dodo-inline-checkout"></div>.

Step-by-Step Integration Guide

1

Install the SDK

Install the Dodo Payments Checkout SDK:
2

Initialize the SDK for Inline Display

Initialize the SDK and specify displayType: 'inline'. You should also listen for the checkout.breakdown event to update your UI with real-time tax and total calculations.
3

Create a Container Element

Add an element to your HTML where the checkout frame will be injected:
4

Open the Checkout

Call DodoPayments.Checkout.open() with the checkoutUrl and the elementId of your container:
5

Test Your Integration

  1. Start your development server:
  1. Test the checkout flow:
    • Enter your email and address details in the inline frame.
    • Verify that your custom order summary updates in real-time.
    • Test the payment flow using test credentials.
    • Confirm redirects work correctly.
You should see checkout.breakdown events logged in your browser console if you added a console log in the onEvent callback.
6

Go Live

When you’re ready for production:
  1. Change the mode to 'live':
  1. Update your checkout URLs to use live checkout sessions from your backend.
  2. Test the complete flow in production.

Complete React Example

This example demonstrates how to implement a custom order summary alongside the inline checkout, keeping them in sync using the checkout.breakdown event.

API Reference

Configuration

Initialize Options

Checkout Options

Methods

Open Checkout

Opens the checkout frame in the specified container.
You can also pass additional options to customize the checkout behavior:

إغلاق الدفع

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

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

يعيد ما إذا كان إطار الدفع محقون حاليًا.

الأحداث

يوفر SDK أحداثًا في الوقت الفعلي من خلال onEvent. يعتبر checkout.breakdown مفيدًا بشكل خاص لمزامنة واجهة المستخدم الخاصة بك.

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

يوفر حدث checkout.breakdown البيانات التالية:

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

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

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

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

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

تنفيذ CDN

للتكامل السريع بدون خطوة البناء، يمكنك استخدام CDN الخاص بنا:

تحديث طريقة الدفع

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

كيف يعمل

  1. استدعاء API تحديث طريقة الدفع للحصول على payment_link:
  1. قم بتمرير payment_link ك checkoutUrl لفتح الدفع المضمن:
يعرض الإطار المضمن فقط نموذج تجميع طريقة الدفع. يمكن للعملاء إدخال تفاصيل بطاقة جديدة أو اختيار طريقة دفع مخزنة دون مغادرة صفحتك.

للاشتراكات المعلقة

عند تحديث طريقة الدفع لاشتراك في حالة on_hold، فإنه ينشئ Dodo Payments تلقائيًا شحنة لأي مستحقات متبقية. راقب الإشعارات payment.succeeded وsubscription.active لتأكيد إعادة التفعيل.
يمكنك أيضًا استخدام طريقة دفع محفوظة موجودة بدلاً من جمع تفاصيل جديدة عن طريق تمرير type: 'existing' مع payment_method_id إلى واجهة برمجة تطبيقات تحديث طريقة الدفع.

التعامل مع الأخطاء

يوفر SDK معلومات خطأ مفصلة من خلال نظام الأحداث. قم دائمًا بتطبيق معالجة الأخطاء الصحيحة في رد استدعاء onEvent:
تعامل دائمًا مع حدث checkout.error لتقديم تجربة مستخدم جيدة عند حدوث مشاكل.

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

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

التحقق من حالة الدفع

لا تعتمد فقط على أحداث الدفع المضمنة لتحديد نجاح الدفع أو فشله. قم دائمًا بتطبيق التحقق من الخادم باستخدام الإشعارات أو الاستطلاع.

لماذا التحقق من الخادم ضروري

بينما توفر أحداث الدفع المضمنة تغذية راجعة في الوقت الفعلي، يجب ألا تكون مصدر الحقيقة الوحيد لحالة الدفع. يمكن أن تتسبب مشاكل الشبكة أو تعطل المستعرض أو إغلاق المستخدم للصفحة في عدم تلقي الأحداث. لضمان تحقق موثوق من الدفع:
  1. يجب أن يستمع الخادم الخاص بك إلى أحداث webhook - يرسل Dodo Payments إشعارات لتغييرات حالة الدفع
  2. تطبيق آلية الاستطلاع - يجب ان يقوم الواجهة الأمامية الخاصة بك باستطلاع الخادم للحصول على تحديثات الحالة
  3. جمع بين النهجين - استخدم الإشعارات كمصدر رئيسي والاستطلاع كبديل

الهندسة المعمارية الموصى بها

خطوات التنفيذ

1. استمع لأحداث الدفع - عند النقر على المستخدم على زر الدفع، ابدأ في التحضير للتحقق من الحالة:
2. استطلاع بالخادم - أنشئ نقطة نهاية تتحقق من قاعدة البيانات الخاصة بك لحالة الدفع (يتم تحديثها بواسطة الإشعارات):
3. عالج الإشعارات من جهة الخادم - قم بتحديث قاعدة البيانات الخاصة بك عندما يرسل Dodo الأحداث payment.succeeded أو payment.failed. راجع وثائق الإشعارات للحصول على التفاصيل.

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

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

تمكين المحافظ الرقمية

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

الإعداد السريع ل Apple Pay

تأكيد النطاق مطلوب فقط للدفع المضمّن داخل الصفحة (inline checkout). الدفع العلوي، الدفع المستضاف، وروابط الدفع لا تحتاج إلى ذلك. يتم التحقق من Apple Pay لكل نطاق من لوحة التحكم. اذهب إلى الإعدادات → طرق الدفع وفي صف Apple Pay، انقر على إدارة النطاقات. Manage domains button on the Apple Pay row in Payment Methods settings من لوحة نطاقات المحفظة، قم بتنزيل ملف الارتباط. Wallet domains panel with the Download file button انقر على تسجيل النطاق وأدخل النطاق حيث تقوم بإدماج الدفع المضمّن (e.g. shop.example.com)، ثم متابعة. Register a domain form with a domain entered استضفه في:
يجب أن يعمل عبر HTTPS، أن يكون قابلاً للوصول بدون إعادة توجيه، وأن يكون مشغلاً مع Content-Type: application/octet-stream أو text/plain. انقر على تأكيد النطاق. تؤكد Dodo Payments أن الملف مباشر وتقدم نطاقك إلى Apple. Verify your domain screen with the association file host path and Verify domain button عندما يظهر الوضع نشطًا، يتم تمكين Apple Pay لهذا النطاق. استخدم المفتاح مفعل لتشغيلها أو إيقافها لكل نطاق. Wallet domains list showing domains with an Active Apple Pay status and Enabled toggles
  1. افتح الدفع على جهاز Apple
  2. تأكد من ظهور زر Apple Pay
  3. أكمل معاملة اختبارية

دعم المتصفح

تدعم حزمة تطوير Dodo Payments Checkout المتصفحات التالية:
  • Chrome (الأحدث)
  • Firefox (الأحدث)
  • Safari (الأحدث)
  • Edge (الأحدث)
  • IE11+

الدفع المضمّن مقابل الدفع العلوي

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

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

استخدم الدفع العلوي لدمج سريع مستند إلى النماذج. أنشئ جلسات دفع لتعزيز تجارب الدفع الخاصة بك. تعامل مع أحداث الدفع من جانب الخادم باستخدام webhooks. دليل كامل لدمج Dodo Payments. لمزيد من المساعدة، قم بزيارة مجتمع Discord الخاص بنا أو اتصل بفريق دعم المطورين لدينا.
آخر تعديل في ٩ يوليو ٢٠٢٦