Checkout Sessions

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.

Preview Checkout

Calculate pricing, taxes, and totals before creating a session.

Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

الروابط ذات الاستخدام الواحد: إن checkout_url الذي تُرجعه API غير قابل لإعادة الاستخدام وتنتهي صلاحيته خلال 24 ساعة (أو 15 دقيقة عند confirm=true). وهو مخصص لعميل واحد لإتمام دفعة واحدة. أنشئ جلسة checkout جديدة لكل عميل ولكل محاولة دفع، بدلاً من مشاركة الرابط أو إعادة استخدامه.

المتطلبات الأساسية

Dodo Payments Account

ستحتاج إلى حساب تاجر نشط لدى Dodo Payments مع إمكانية الوصول إلى API.

API Credentials

أنشئ بيانات اعتماد API من لوحة تحكم Dodo Payments:

Products Setup

أنشئ منتجاتك في لوحة تحكم Dodo Payments قبل تنفيذ جلسات checkout.

إنشاء أول جلسة Checkout

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

// Initialize the Dodo Payments client
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

import os
from dodopayments import DodoPayments

# Initialize the Dodo Payments client
client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

def create_checkout_session():
    """
    Create a checkout session for a single product with customer data pre-filled.
    Returns the session object containing checkout_url for customer redirection.
    """
    try:
        session = client.checkout_sessions.create(
            # Products to sell - use IDs from your Dodo Payments dashboard
            product_cart=[
                {
                    "product_id": "prod_123",  # Replace with your actual product ID
                    "quantity": 1
                }
            ],
            
            # Pre-fill customer information to reduce checkout friction
            customer={
                "email": "customer@example.com",
                "name": "John Doe",
                "phone_number": "+1234567890"
            },
            
            # Billing address for tax calculation and compliance
            billing_address={
                "street": "123 Main St",
                "city": "San Francisco", 
                "state": "CA",
                "country": "US",  # Required: ISO 3166-1 alpha-2 country code
                "zipcode": "94102"
            },
            
            # Where to redirect after successful payment
            return_url="https://yoursite.com/checkout/success",
            
            # Custom data for your internal tracking
            metadata={
                "order_id": "order_123",
                "source": "web_app"
            }
        )
        
        # Redirect your customer to this URL to complete payment
        print(f"Checkout URL: {session.checkout_url}")
        print(f"Session ID: {session.session_id}")
        
        return session
        
    except Exception as error:
        print(f"Failed to create checkout session: {error}")
        raise error

# Example usage in a Flask route
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    try:
        session = create_checkout_session()
        return jsonify({"checkout_url": session.checkout_url})
    except Exception as error:
        return jsonify({"error": "Failed to create checkout session"}), 500

// Direct API call using fetch - useful for any JavaScript environment
async function createCheckoutSession() {
  try {
    const response = await fetch('https://test.dodopayments.com/checkouts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
      },
      body: JSON.stringify({
        // Products to sell - use IDs from your Dodo Payments dashboard
        product_cart: [
          {
            product_id: 'prod_123', // Replace with your actual product ID
            quantity: 1
          }
        ],
        
        // Pre-fill customer information to reduce checkout friction
        customer: {
          email: 'customer@example.com',
          name: 'John Doe',
          phone_number: '+1234567890'
        },
        
        // Billing address for tax calculation and compliance
        billing_address: {
          street: '123 Main St',
          city: 'San Francisco',
          state: 'CA', 
          country: 'US', // Required: ISO 3166-1 alpha-2 country code
          zipcode: '94102'
        },
        
        // Where to redirect after successful payment
        return_url: 'https://yoursite.com/checkout/success',
        
        // Custom data for your internal tracking
        metadata: {
          order_id: 'order_123',
          source: 'web_app'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const session = await response.json();
    
    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example: Redirect user to checkout
createCheckoutSession().then(session => {
  window.location.href = session.checkout_url;
});

استجابة API

تعيد جميع الطرق أعلاه بنية الاستجابة نفسها:

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

إن checkout_url الذي تم إنشاؤه مخصص للاستخدام مرة واحدة وتنتهي صلاحيته خلال 24 ساعة. لا تخزّنه مؤقتًا أو تعِد استخدامه مع عملاء أو محاولات دفع مختلفة — أنشئ جلسة checkout جديدة كلما احتجت إلى رابط جديد.

Get the checkout URL

استخرج checkout_url من استجابة API.

Redirect your customer

وجّه عميلك إلى عنوان URL الخاص بـ checkout لإتمام عملية الشراء.

// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');

خيارات التكامل البديلة: بدلاً من إعادة التوجيه، يمكنك تضمين checkout مباشرةً في صفحتك باستخدام Overlay Checkout (نافذة تراكب منبثقة) أو Inline Checkout (تضمين كامل). وفي تطبيق جوّال أصلي، مرّر عنوان URL نفسه إلى Mobile Checkout SDKs لنظام Android أو iOS أو React Native أو Flutter. تستخدم جميع هذه الخيارات عنوان URL نفسه لجلسة checkout.

Handle the return

بعد الدفع، يُعاد توجيه العملاء إلى return_url الخاص بك مع query parameters تتضمن معرّف الدفع/الاشتراك، والحالة، والبريد الإلكتروني للعميل، وأي مفاتيح ترخيص. راجع مستندات معاملات return_url للاطلاع على القائمة الكاملة.

Request Body

Required Fields

الحقول الأساسية المطلوبة لكل جلسة checkout

Optional Fields

إعدادات إضافية لتخصيص تجربة checkout

الحقول المطلوبة

array

مطلوب

مصفوفة المنتجات المراد تضمينها في جلسة checkout. يجب أن يحتوي كل منتج على product_id صالح من لوحة تحكم Dodo Payments.

Checkout المختلط: يمكنك الجمع بين منتجات الدفع لمرة واحدة ومنتجات الاشتراك في جلسة checkout نفسها. يتيح ذلك حالات استخدام متقدمة مثل رسوم الإعداد مع الاشتراكات، وحزم الأجهزة مع SaaS، وغير ذلك.

إظهار Product Cart Item Properties

string

مطلوب

المعرّف الفريد للمنتج من لوحة تحكم Dodo Payments.مثال: "prod_123abc456def"

integer

مطلوب

كمية المنتج.مثال: 1 لعنصر واحد، و3 لكميات متعددة

array

مصفوفة الإضافات المراد إرفاقها بالمنتج. تكون صالحة فقط إذا كان المنتج اشتراكًا.

إظهار Addon item properties

string

مطلوب

integer

مطلوب

integer

المبلغ الذي يدفعه العميل عند تفعيل pay_what_you_want. وإذا كان معطلاً، فسيتم تجاهل هذا الحقل.التنسيق: يُمثّل بأصغر وحدة من العملة (مثل السنتات بالنسبة إلى USD). على سبيل المثال، لفرض رسم قدره $1.00، مرّر 100.

array

تجاوزات خاصة بكل جلسة checkout لاستحقاقات الأرصدة المرتبطة بالمنتج مسبقًا. استخدم ذلك لمنح عدد مختلف من الأرصدة لهذه الجلسة وحدها — مثل حزمة ترويجية تمنح 1,000 رصيد API بدلاً من 500 رصيد افتراضي للمنتج — دون إنشاء منتج منفصل.

يجب أن يكون كل credit_entitlement_id مرتبطًا بالمنتج مسبقًا. يتجاوز هذا الحقل فقط credits_amount الممنوح عند إتمام هذه الجلسة؛ بينما تظل إعدادات استحقاق الأرصدة على مستوى المنتج (مثل انتهاء الصلاحية وإعادة الترحيل وغيرهما) سارية.

إظهار Credit entitlement override properties

string

مطلوب

معرّف استحقاق الرصيد المراد تجاوزه. يجب أن يكون مرتبطًا بالمنتج مسبقًا.

string

مطلوب

عدد الأرصدة المراد منحها لهذه الجلسة، مع تجاوز credits_amount على مستوى المنتج. يجب أن يكون أكبر من الصفر.

العثور على معرّفات منتجاتك: يمكنك العثور على معرّفات المنتجات في لوحة تحكم Dodo Payments ضمن Products → View Details، أو باستخدام List Products API.

الحقول الاختيارية

اضبط هذه الحقول لتخصيص تجربة checkout وإضافة منطق الأعمال إلى تدفق الدفع.

Customer Information

object

معلومات العميل. يمكنك إما إرفاق عميل موجود باستخدام معرّفه، أو إنشاء سجل عميل جديد أثناء checkout.

Attach Existing Customer
New Customer

إرفاق عميل موجود بجلسة checkout باستخدام معرّفه.

إظهار Existing Customer Properties

string

مطلوب

المعرّف الفريد لعميل موجود. استخدمه لإرفاق جلسة checkout بعميل موجود بدلاً من إنشاء عميل جديد.

إنشاء سجل عميل جديد أثناء checkout.

إظهار New Customer Properties

string

مطلوب

عنوان البريد الإلكتروني للعميل. مطلوب عند إنشاء عميل جديد.

string

الاسم الكامل للعميل كما يجب أن يظهر في الإيصالات والفواتير.مثال: "John Doe" أو "Jane Smith"

string

رقم هاتف العميل بالتنسيق الدولي. مطلوب لبعض طرق الدفع ولمنع الاحتيال.التنسيق: أدرج رمز الدولة، مثل "+1234567890" لأرقام الولايات المتحدة

object

معلومات عنوان الفوترة لحساب الضرائب بدقة، ومنع الاحتيال، والامتثال للمتطلبات التنظيمية.

عند ضبط confirm على true، تصبح جميع حقول عنوان الفوترة مطلوبة لإنشاء الجلسة بنجاح.

إظهار Billing address object properties

string

العنوان الكامل للشارع، بما في ذلك رقم المنزل واسم الشارع ورقم الشقة/الوحدة عند الحاجة.مثال: "123 Main St, Apt 4B" أو "456 Oak Avenue"

string

اسم المدينة أو البلدية.مثال: "San Francisco"، أو "New York"، أو "London"

string

اسم الولاية أو المقاطعة أو المنطقة. استخدم الأسماء الكاملة أو الاختصارات القياسية.مثال: "California" أو "CA"، أو "Ontario" أو "ON"

string

مطلوب

رمز الدولة المكوّن من حرفين وفق ISO (ISO 3166-1 alpha-2). يكون هذا الحقل مطلوبًا دائمًا عند تقديم billing_address.أمثلة: "US" (الولايات المتحدة)، "CA" (كندا)، "GB" (المملكة المتحدة)، "DE" (ألمانيا)

Country Code Reference

عرض القائمة الكاملة للدول المدعومة ورموز ISO الخاصة بها

string

الرمز البريدي أو ZIP أو ما يعادله وفقًا لمتطلبات الدولة.أمثلة: "94102" (الولايات المتحدة)، "M5V 3A8" (كندا)، "SW1A 1AA" (المملكة المتحدة)

Payment Configuration

array

تحكّم في طرق الدفع المتاحة للعملاء أثناء checkout. يساعد ذلك على تحسين التجربة لأسواق أو متطلبات أعمال محددة.الخيارات المتاحة: credit، debit، upi_collect، apple_pay، google_pay، amazon_pay، klarna، affirm، afterpay_clearpay، cashapp، multibanco، bancontact_card، eps، ideal، przelewy24، paypal

مهم: أدرج دائمًا credit وdebit كخيارين احتياطيين لمنع فشل checkout عند عدم توفر طرق الدفع المفضلة.

مثال:

["apple_pay", "google_pay", "credit", "debit"]

string

تجاوز اختيار العملة الافتراضي باستخدام عملة فوترة ثابتة. يستخدم رموز العملات وفق ISO 4217.العملات المدعومة: USD، EUR، GBP، CAD، AUD، INR، وغير ذلكمثال: "USD" للدولار الأمريكي، و"EUR" لليورو

لا يكون هذا الحقل فعالًا إلا عند تفعيل التسعير التكيفي. وإذا كان التسعير التكيفي معطلاً، فستُستخدم العملة الافتراضية للمنتج.

boolean

افتراضي:"false"

عرض طرق الدفع المحفوظة مسبقًا للعملاء العائدين، مما يحسّن سرعة checkout وتجربة المستخدم.

Session Management

string

عنوان URL لإعادة توجيه العملاء بعد إتمام الدفع. تضيف Dodo Payments معاملات الاستعلام التالية إلى عنوان URL عند إعادة التوجيه:

المعرّف	النوع	الحالة
`payment_id`	`string`	موجود دائمًا للدفعات لمرة واحدة
`subscription_id`	`string`	موجود دائمًا لدفعات الاشتراك
`status`	`string`	موجود دائمًا
`license_key`	`string`	موجود إذا كانت مفاتيح الترخيص مفعّلة للمنتج. وتُفصل بفواصل عند وجود عدة مفاتيح
`email`	`string`	موجود إذا كان للعميل بريد إلكتروني مسجل

أمثلة على عناوين URL لإعادة التوجيه:

# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription payment with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

# Payment without license keys
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com

استخدم معاملات الاستعلام license_key وemail لعرض مفاتيح الترخيص أو إرسال تأكيد فورًا في صفحة العودة، دون الحاجة إلى استدعاء API إضافي.

string

عنوان URL لإعادة توجيه العملاء عند النقر على زر الرجوع أو إلغاء جلسة checkout. إذا لم يتم توفيره، فلن يُعرض زر الرجوع.

عيّن cancel_url لتوفير طريقة واضحة للعملاء للعودة إلى موقعك دون إتمام عملية الشراء. يحسّن ذلك تجربة checkout ويقلل الاحتكاك.

boolean

افتراضي:"false"

عند ضبطه على true، يُنهي جميع تفاصيل الجلسة فورًا. وستُصدر API خطأً إذا كانت البيانات المطلوبة مفقودة.

array

طبّق رمز خصم واحدًا أو أكثر بشكل متسلسل على جلسة checkout. تُطبّق الرموز بترتيب المصفوفة (يخفض الرمز الأول السعر الأساسي، ثم يخفض الرمز الثاني السعر بعد الخصم، وهكذا)، بحد أقصى 20 رمزًا لكل جلسة.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

الحقل المفرد discount_code أدناه متوقف لكنه لا يزال مدعومًا بالكامل — وتستمر عمليات التكامل الحالية في العمل دون تغييرات. لا يمكن دمجه مع discount_codes في الطلب نفسه. انتقل إلى discount_codes عندما يناسبك للاستفادة من التطبيق المتسلسل.

string

مهمل

متوقف — يُفضّل استخدام discount_codes لعمليات التكامل الجديدة. لا يزال هذا الحقل يعمل للتوافق مع الإصدارات السابقة، لكنه لا يمكن دمجه مع discount_codes في الطلب نفسه.

object

أزواج مخصصة من المفتاح والقيمة لتخزين معلومات إضافية حول الجلسة.

boolean

تجاوز سلوك merchant الافتراضي لـ 3DS لهذه الجلسة.

boolean

افتراضي:"false"

فعّل وضع جمع العنوان المختصر. عند تفعيله، يجمع checkout فقط:

الدولة: مطلوبة دائمًا لتحديد الضرائب
ZIP/الرمز البريدي: في المناطق التي تحتاج إليه فقط لحساب ضريبة المبيعات أو VAT أو GST

يقلل ذلك احتكاك checkout بشكل كبير من خلال إزالة حقول النموذج غير الضرورية.

فعّل العنوان المختصر لإتمام checkout بسرعة أكبر. يظل جمع العنوان الكامل متاحًا للأنشطة التجارية التي تتطلب تفاصيل فوترة كاملة.

UI Customization & Features

object

خصّص مظهر واجهة checkout وسلوكها.

إظهار Customization object properties

string

افتراضي:"system"

نسق واجهة checkout. الخيارات: light أو dark أو system.

boolean

افتراضي:"true"

اعرض قسم تفاصيل الطلب في واجهة checkout.

boolean

افتراضي:"true"

اعرض وسم “on-demand” للمنتجات المنطبقة.

string

أجبر واجهة checkout على العرض بلغة محددة. يكتشف checkout لغة متصفح العميل تلقائيًا بشكل افتراضي.رموز اللغات المدعومة: ar (العربية)، ca (الكتالانية)، de (الألمانية)، en (الإنجليزية)، es (الإسبانية)، fr (الفرنسية)، he (العبرية)، id (الإندونيسية)، it (الإيطالية)، ja (اليابانية)، ko (الكورية)، ms (الماليزية)، nl (الهولندية)، pl (البولندية)، pt (البرتغالية)، ro (الرومانية)، ru (الروسية)، sv (السويدية)، th (التايلاندية)، tr (التركية)، zh (الصينية)مثال: "es" للإسبانية، و"ja" لليابانية

object

اضبط الميزات والسلوكيات المحددة لجلسة checkout.

إظهار Feature flags object properties

boolean

افتراضي:"true"

السماح للعملاء باختيار عملتهم المفضلة أثناء checkout.

boolean

افتراضي:"true"

اعرض حقل إدخال رمز الخصم في واجهة checkout.

boolean

افتراضي:"false"

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

boolean

افتراضي:"true"

جمع أرقام هواتف العملاء أثناء checkout.

boolean

افتراضي:"true"

السماح للعملاء بإدخال أرقام التعريف الضريبي.

boolean

افتراضي:"false"

فرض إنشاء سجل عميل جديد بدلاً من تحديث السجلات الموجودة.

boolean

السماح للعملاء بتعديل عناوين بريدهم الإلكتروني أثناء checkout.

boolean

السماح للعملاء بتعديل أسمائهم أثناء checkout.

boolean

السماح للعملاء بتعديل عنوان الشارع أثناء checkout.

boolean

السماح للعملاء بتعديل المدينة أثناء checkout.

boolean

السماح للعملاء بتعديل الولاية أثناء checkout.

boolean

السماح للعملاء بتعديل الدولة أثناء checkout.

boolean

السماح للعملاء بتعديل الرمز البريدي أثناء checkout.

boolean

افتراضي:"false"

تخطَّ صفحة نجاح الدفع الافتراضية وأعد توجيه العملاء فورًا إلى return_url بعد إتمام الدفع.

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

Custom Fields

array

اجمع معلومات إضافية من العملاء أثناء checkout باستخدام حقول نموذج مخصصة. يمكنك تعريف ما يصل إلى 5 حقول مخصصة لكل جلسة checkout. تُضمّن إجابات العملاء في حمولات webhook وتتوفر عبر API.

إظهار Custom field object properties

string

مطلوب

المعرّف الفريد لهذا الحقل. يُستخدم كمفتاح في حمولات webhook واستجابات API.مثال: "company_name"، "referral_source"، "team_size"

string

مطلوب

التسمية المعروضة للعميل في نموذج checkout.مثال: "Company Name"، "How did you hear about us?"، "Team Size"

string

مطلوب

نوع الحقل الذي يحدد قواعد التحقق من الإدخال.الأنواع المتاحة:

text - إدخال نصي بسطر واحد
number - إدخال رقمي
email - عنوان بريد إلكتروني مع التحقق
url - عنوان URL مع التحقق
date - منتقي التاريخ
dropdown - الاختيار من خيارات محددة مسبقًا
boolean - مفتاح تبديل نعم/لا

boolean

افتراضي:"false"

ما إذا كان يجب ملء هذا الحقل قبل إتمام checkout.

string

النص النائب المعروض في حقل الإدخال.

array

قائمة الخيارات لنوع الحقل dropdown. مطلوبة عندما يكون field_type هو dropdown، ويتم تجاهلها للأنواع الأخرى.مثال: ["Google", "Twitter", "Friend referral", "Other"]

تُضمّن إجابات العملاء عن الحقول المخصصة في:

Webhooks: تحتوي payment.succeeded وsubscription.active وغيرها من حمولات الأحداث ذات الصلة على مصفوفة custom_field_responses
استجابات API: تتضمن كائنات الدفع والاشتراك custom_field_responses

Subscription Configuration

object

إعدادات إضافية لجلسات checkout التي تتضمن منتجات اشتراك.

إظهار Subscription data object properties

integer

عدد أيام الفترة التجريبية قبل أول عملية خصم. يجب أن يتراوح بين 0 و10000 يوم.لا يمكن ضبط مبلغ تجربة مدفوعة لكل جلسة — اضبط trial_amount على السعر المتكرر للمنتج بدلاً من ذلك. راجع التجارب المدفوعة.

object

إعدادات اشتراك on-demand للفوترة القائمة على الاستخدام أو المقاسة.

إظهار On-demand object properties

boolean

مطلوب

إذا تم ضبطه على true، فلن ينفّذ أي عملية خصم، بل سيفوّض تفاصيل طريقة الدفع لاستخدامها مستقبلًا فقط.

integer

سعر المنتج للعملية الأولية التي تُفرض على العميل. وإذا لم يتم تحديده، فسيُستخدم السعر المخزّن للمنتج.التنسيق: يُمثّل بأصغر وحدة من العملة (مثل السنتات بالنسبة إلى USD). على سبيل المثال، لفرض رسم قدره $1.00، مرّر 100.

string

العملة الاختيارية لسعر المنتج. وإذا لم يتم تحديدها، فستكون افتراضيًا عملة المنتج.

string

تجاوز اختياري لوصف المنتج لأغراض الفوترة وبنود الفاتورة. وإذا لم يتم تحديده، فسيُستخدم الوصف المخزّن للمنتج.

boolean

ما إذا كانت رسوم Adaptive Currency يجب تضمينها في سعر المنتج (true) أو إضافتها فوق السعر (false). يتم تجاهلها إذا لم يكن التسعير التكيفي مفعّلاً.

أمثلة على الاستخدام

فيما يلي 10 أمثلة شاملة توضّح إعدادات مختلفة لجلسات checkout لسيناريوهات أعمال متعددة:

1. Checkout لمنتج واحد بسيط

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

2. سلة متعددة المنتجات

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

3. اشتراك مع فترة تجريبية

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. Checkout مؤكد مسبقًا

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

5. Checkout مع تجاوز العملة

لا يسري تجاوز billing_currency إلا عند تفعيل Adaptive Currency في إعدادات حسابك. وإذا كان Adaptive Currency معطلاً، فلن يكون لهذا المعيار أي تأثير.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

6. طرق الدفع المحفوظة للعملاء العائدين

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: 'returning.customer@example.com',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

7. Checkout للشركات مع جمع المعرّف الضريبي

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: 'john.sales@company.com'
  }
});

8. Checkout بنمط داكن مع رموز خصم متسلسلة

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_gaming_chair',
      quantity: 1
    }
  ],
  discount_codes: ['BLACKFRIDAY2024'],
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

9. طرق دفع إقليمية (UPI للهند)

للحصول على معلومات تفصيلية حول إعداد UPI واختباره، راجع صفحة طرق الدفع في الهند.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

10. Checkout بخدمة BNPL (اشترِ الآن وادفع لاحقًا)

للحصول على معلومات تفصيلية حول إعداد BNPL واختباره، راجع صفحة اشترِ الآن وادفع لاحقًا (BNPL).

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

11. استخدام طرق الدفع الحالية لإتمام checkout فورًا

استخدم طريقة الدفع المحفوظة للعميل لإنشاء جلسة checkout تُعالج فورًا، مع تخطي جمع طريقة الدفع:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});

عند استخدام payment_method_id، يجب ضبط confirm على true وتوفير customer_id موجود. سيتم التحقق من أهلية طريقة الدفع باستخدام عملة الدفع.

يجب أن تكون طريقة الدفع مملوكة للعميل ومتوافقة مع عملة الدفع. يتيح ذلك عمليات الشراء بنقرة واحدة للعملاء العائدين.

12. روابط مختصرة لعناوين دفع أوضح

أنشئ روابط دفع مختصرة قابلة للمشاركة باستخدام slugs مخصصة:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123

تُعد الروابط المختصرة مثالية للمشاركة عبر SMS أو البريد الإلكتروني أو وسائل التواصل الاجتماعي. فهي أسهل في التذكر وتبني ثقة أكبر لدى العملاء مقارنةً بعناوين URL الطويلة.

13. تخطي صفحة نجاح الدفع مع إعادة التوجيه الفورية

أعد توجيه العملاء فورًا بعد إتمام الدفع، مع تجاوز صفحة النجاح الافتراضية:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  }
});

استخدم redirect_immediately: true عندما تكون لديك صفحة نجاح مخصصة توفر تجربة مستخدم أفضل من صفحة نجاح الدفع الافتراضية. ويفيد ذلك خصوصًا في تطبيقات الجوال وتدفقات checkout المضمّنة.

عند تفعيل redirect_immediately، يُعاد توجيه العملاء إلى return_url فورًا بعد إتمام الدفع، مع تخطي صفحة النجاح الافتراضية بالكامل.

14. فرض لغة محددة

أجبر checkout على العرض بلغة محددة، متجاوزًا اكتشاف لغة متصفح العميل:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ],
  customization: {
    force_language: 'ja'  // Force Japanese language
  },
  customer: {
    email: 'customer@example.jp',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});

استخدم force_language عندما تعرف اللغة المفضلة للعميل (مثلًا من إعدادات حسابه)، أو عند استهداف أسواق إقليمية محددة.

اللغات المدعومة: العربية (ar)، الكتالانية (ca)، الصينية (zh)، الهولندية (nl)، الإنجليزية (en)، الفرنسية (fr)، الألمانية (de)، العبرية (he)، الإندونيسية (id)، الإيطالية (it)، اليابانية (ja)، الكورية (ko)، الماليزية (ms)، البولندية (pl)، البرتغالية (pt)، الرومانية (ro)، الروسية (ru)، الإسبانية (es)، السويدية (sv)، التايلاندية (th)، التركية (tr)

15. جمع الحقول المخصصة

اجمع معلومات إضافية من العملاء أثناء checkout باستخدام الحقول المخصصة:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_saas_plan',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true,
      placeholder: 'Acme Inc.'
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '201-500', '500+']
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      required: false,
      options: ['Google', 'Twitter', 'Friend referral', 'Blog post', 'Other']
    },
    {
      key: 'website',
      label: 'Company Website',
      field_type: 'url',
      required: false,
      placeholder: 'https://example.com'
    }
  ],
  customer: {
    email: 'buyer@company.com',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});

تُضمّن إجابات الحقول المخصصة تلقائيًا في حمولات webhook (payment.succeeded وsubscription.active وغيرهما)، ويمكن استردادها عبر API. استخدمها لإثراء CRM، أو تشغيل تدفقات الإعداد، أو تخصيص تجربة العميل.

أنواع الحقول المتاحة: text، number، email، url، date، dropdown، boolean

معاينة جلسات Checkout

قبل إنشاء جلسة checkout، يمكنك معاينة تفاصيل السعر، بما في ذلك الضرائب والخصومات والإجماليات. يفيد ذلك في عرض أسعار دقيقة للعملاء قبل انتقالهم إلى checkout.

عندما تحتوي السلة على منتج اشتراك، تعيد استجابة المعاينة أيضًا next_billing_date — وهي معاينة لتاريخ الفوترة القادم، بحيث يمكنك عرضه قبل إنشاء الاشتراك. ويُحسب نسبيًا إلى الوقت الحالي: now + trial period عند تطبيق تجربة، وإلا فـ now + one payment frequency. يُحذف الحقل من السلال التي تحتوي على منتجات لمرة واحدة فقط. وهذا تقدير يستند إلى وقت المعاينة؛ أما next_billing_date المعتمد فيُحدد عند تفعيل الاشتراك.

تعيد المعاينة أيضًا trial_period_days (مدة التجربة الفعلية، المجانية أو المدفوعة) وtrial_amount (رسوم التجربة لكل وحدة بعد الخصومات، بأصغر وحدات عملة السعر). لا يظهر trial_amount إلا في التجربة المدفوعة، ويكون null للتجربة المجانية أو عند عدم وجود تجربة. استخدم current_breakup للإجمالي الخاضع للضريبة المستحق فعليًا اليوم.

Node.js SDK
Python SDK

const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'prod_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_codes: ['SAVE20']
});

console.log('Subtotal:', preview.subtotal);
console.log('Tax:', preview.tax);
console.log('Discount:', preview.discount);
console.log('Total:', preview.total);

// Present only when the cart contains a subscription product
console.log('Next billing date:', preview.next_billing_date);

preview = client.checkout_sessions.preview(
    product_cart=[
        {"product_id": "prod_123", "quantity": 1}
    ],
    billing_address={
        "country": "US",
        "state": "CA",
        "zipcode": "94102"
    },
    discount_codes=["SAVE20"]
)

print(f"Subtotal: {preview.subtotal}")
print(f"Tax: {preview.tax}")
print(f"Discount: {preview.discount}")
print(f"Total: {preview.total}")

# Present only when the cart contains a subscription product
print(f"Next billing date: {preview.next_billing_date}")

Preview API Reference

عرض الوثائق الكاملة لنقطة نهاية المعاينة.

الانتقال من الروابط الديناميكية إلى جلسات Checkout

الاختلافات الرئيسية

سابقًا، عند إنشاء رابط دفع باستخدام Dynamic Links، كان يتعين عليك توفير عنوان الفوترة الكامل للعميل. مع Checkout Sessions، لم يعد ذلك ضروريًا. يمكنك ببساطة تمرير أي معلومات متوفرة لديك، وسنتولى الباقي. على سبيل المثال:

إذا كنت تعرف دولة فوترة العميل فقط، فما عليك سوى توفيرها.
سيجمع تدفق checkout التفاصيل المفقودة تلقائيًا قبل نقل العميل إلى صفحة الدفع.
من ناحية أخرى، إذا كانت لديك جميع المعلومات المطلوبة بالفعل وتريد الانتقال مباشرةً إلى صفحة الدفع، فيمكنك تمرير مجموعة البيانات الكاملة وتضمين confirm=true في request body.

عملية الترحيل

الانتقال من Dynamic Links إلى Checkout Sessions مباشر:

Update your integration

حدّث عملية التكامل لديك لاستخدام طريقة API أو SDK الجديدة.

Adjust request payload

اضبط حمولة الطلب وفق تنسيق Checkout Sessions.

That's it!

نعم. لا تحتاج إلى أي معالجة إضافية أو خطوات ترحيل خاصة من جانبك.

مرجع API ذي صلة

Create Checkout Session

مرجع API الكامل لإنشاء جلسات checkout مع جميع المعاملات والخيارات المتاحة

Preview Checkout Session

مرجع API لمعاينة الأسعار والضرائب والإجماليات قبل إنشاء جلسة

آخر تعديل في ٣١ يوليو ٢٠٢٦

Integration Guides

Billing Deconstructions

Cookbooks

Quick Start Guide

API Reference & Live Testing

Preview Checkout

المتطلبات الأساسية

إنشاء أول جلسة Checkout

استجابة API

Request Body

Required Fields

Optional Fields

الحقول المطلوبة

الحقول الاختيارية

Country Code Reference

أمثلة على الاستخدام

1. Checkout لمنتج واحد بسيط

2. سلة متعددة المنتجات

3. اشتراك مع فترة تجريبية

4. Checkout مؤكد مسبقًا

5. Checkout مع تجاوز العملة

6. طرق الدفع المحفوظة للعملاء العائدين

7. Checkout للشركات مع جمع المعرّف الضريبي

8. Checkout بنمط داكن مع رموز خصم متسلسلة

9. طرق دفع إقليمية (UPI للهند)

10. Checkout بخدمة BNPL (اشترِ الآن وادفع لاحقًا)

11. استخدام طرق الدفع الحالية لإتمام checkout فورًا

12. روابط مختصرة لعناوين دفع أوضح

13. تخطي صفحة نجاح الدفع مع إعادة التوجيه الفورية

14. فرض لغة محددة

15. جمع الحقول المخصصة

معاينة جلسات Checkout

Preview API Reference

الانتقال من الروابط الديناميكية إلى جلسات Checkout

الاختلافات الرئيسية

عملية الترحيل

مرجع API ذي صلة

Create Checkout Session

Preview Checkout Session

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​المتطلبات الأساسية

​إنشاء أول جلسة Checkout

​استجابة API

​Request Body

Required Fields

Optional Fields

​الحقول المطلوبة

​الحقول الاختيارية

Country Code Reference

​أمثلة على الاستخدام

​1. Checkout لمنتج واحد بسيط

​2. سلة متعددة المنتجات

​3. اشتراك مع فترة تجريبية

​4. Checkout مؤكد مسبقًا

​5. Checkout مع تجاوز العملة

​6. طرق الدفع المحفوظة للعملاء العائدين

​7. Checkout للشركات مع جمع المعرّف الضريبي

​8. Checkout بنمط داكن مع رموز خصم متسلسلة

​9. طرق دفع إقليمية (UPI للهند)

​10. Checkout بخدمة BNPL (اشترِ الآن وادفع لاحقًا)

​11. استخدام طرق الدفع الحالية لإتمام checkout فورًا

​12. روابط مختصرة لعناوين دفع أوضح

​13. تخطي صفحة نجاح الدفع مع إعادة التوجيه الفورية

​14. فرض لغة محددة

​15. جمع الحقول المخصصة

​معاينة جلسات Checkout

Preview API Reference

​الانتقال من الروابط الديناميكية إلى جلسات Checkout

​الاختلافات الرئيسية

​عملية الترحيل

​مرجع API ذي صلة

Create Checkout Session

Preview Checkout Session

المتطلبات الأساسية

إنشاء أول جلسة Checkout

استجابة API

Request Body

الحقول المطلوبة

الحقول الاختيارية

أمثلة على الاستخدام

1. Checkout لمنتج واحد بسيط

2. سلة متعددة المنتجات

3. اشتراك مع فترة تجريبية

4. Checkout مؤكد مسبقًا

5. Checkout مع تجاوز العملة

6. طرق الدفع المحفوظة للعملاء العائدين

7. Checkout للشركات مع جمع المعرّف الضريبي

8. Checkout بنمط داكن مع رموز خصم متسلسلة

9. طرق دفع إقليمية (UPI للهند)

10. Checkout بخدمة BNPL (اشترِ الآن وادفع لاحقًا)

11. استخدام طرق الدفع الحالية لإتمام checkout فورًا

12. روابط مختصرة لعناوين دفع أوضح

13. تخطي صفحة نجاح الدفع مع إعادة التوجيه الفورية

14. فرض لغة محددة

15. جمع الحقول المخصصة

معاينة جلسات Checkout

الانتقال من الروابط الديناميكية إلى جلسات Checkout

الاختلافات الرئيسية

عملية الترحيل

مرجع API ذي صلة