دليل تكامل الهاتف المحمول

​

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

• حساب Dodo Payments: حساب تاجر نشط مع إمكانية الوصول إلى API
• بيانات اعتماد API: مفتاح API ومفتاح سرّي لـ webhook من لوحة التحكم
• مشروع تطبيق محمول: تطبيق Android أو iOS أو React Native أو Flutter
• خادم خلفي: لمعالجة إنشاء جلسات الدفع بأمان

​

سير عمل التكامل

func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
    let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
    
    let requestData: [String: Any] = [
        "productId": productId,
        "customerEmail": customerEmail,
        "customerName": customerName
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
    return response.checkout_url
}

suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
    val client = OkHttpClient()
    val requestBody = JSONObject().apply {
        put("productId", productId)
        put("customerEmail", customerEmail)
        put("customerName", customerName)
    }.toString().toRequestBody("application/json".toMediaType())
    
    val request = Request.Builder()
        .url("https://your-backend.com/api/create-checkout-session")
        .header("Authorization", "Bearer $userSessionToken")
        .post(requestBody)
        .build()
    
    val response = client.newCall(request).execute()
    val responseBody = response.body?.string()
    val jsonResponse = JSONObject(responseBody ?: "")
    return jsonResponse.getString("checkout_url")
}

const getCheckoutURL = async (productId, customerEmail, customerName) => {
  try {
    const response = await fetch('https://your-backend.com/api/create-checkout-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${userSessionToken}`,
      },
      body: JSON.stringify({
        productId,
        customerEmail,
        customerName
      })
    });
    
    const data = await response.json();
    return data.checkout_url;
  } catch (error) {
    console.error('Failed to get checkout URL:', error);
    throw error;
  }
};

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String> getCheckoutUrl({
  required String productId,
  required String customerEmail,
  required String customerName,
}) async {
  final response = await http.post(
    Uri.parse('https://your-backend.com/api/create-checkout-session'),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $userSessionToken',
    },
    body: jsonEncode({
      'productId': productId,
      'customerEmail': customerEmail,
      'customerName': customerName,
    }),
  );

  if (response.statusCode != 200) {
    throw Exception('Failed to get checkout URL: ${response.statusCode}');
  }
  return jsonDecode(response.body)['checkout_url'] as String;
}

​

اختر حزمة SDK

​

تسجيل مخطط عنوان URL لاستدعاء الإرجاع

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

​

تخصيص المظهر

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

val result = DodoCheckout.start(
    activity,
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
        )
    )
) { event -> }

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

​

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

​

وصفات محسّنة للأجهزة المحمولة

Minimal Mobile Checkout - fastest path to payment

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

• Node.js SDK
• Python SDK

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  return_url: 'myapp://checkout/success',
  cancel_url: 'myapp://checkout/cancelled',
  billing_currency: 'USD',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  feature_flags: {
    allow_discount_code: false,
    allow_currency_selection: false,
  },
});

console.log(session.checkout_url);

See all 26 lines

import os
import dodopayments

client = dodopayments.DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    return_url="myapp://checkout/success",
    cancel_url="myapp://checkout/cancelled",
    billing_currency="USD",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "system",
    },
    feature_flags={
        "allow_discount_code": False,
        "allow_currency_selection": False,
    },
)

print(session.checkout_url)

See all 27 lines

راجع Checkout Sessions للاطلاع على جميع المعلَمات المتاحة وقيمها الافتراضية.

Branded Mobile Checkout - custom colors, fonts, and button label

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

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'dark',
    theme_config: {
      dark: {
        button_primary: '#7C3AED',
        button_primary_hover: '#6D28D9',
        button_text_primary: '#FFFFFF',
        bg_primary: '#1A1A2E',
        bg_secondary: '#16213E',
        text_primary: '#E2E8F0',
      },
      pay_button_text: 'Complete Purchase',
      radius: '8px',
    },
  },
});

See all 24 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "dark",
        "theme_config": {
            "dark": {
                "button_primary": "#7C3AED",
                "button_primary_hover": "#6D28D9",
                "button_text_primary": "#FFFFFF",
                "bg_primary": "#1A1A2E",
                "bg_secondary": "#16213E",
                "text_primary": "#E2E8F0",
            },
            "pay_button_text": "Complete Purchase",
            "radius": "8px",
        },
    },
)

See all 24 lines

يقبل theme_config كائنَي dark وlight منفصلين، كي تتكيف لوحة الألوان مع المظهر الحالي للجهاز. راجع Checkout Sessions للاطلاع على المرجع الكامل لمفاتيح الألوان.

One-Click Returning Customer - saved card, instant confirmation

استخدم هذه الوصفة للمستخدمين المسجّلين الذين سبق لهم الدفع. اجمع بين معرّف العميل وطريقة الدفع المحفوظة الخاصة به وconfirm: true لتجاوز نموذج الدفع بالكامل.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { customer_id: 'cus_returning_customer_id' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  payment_method_id: 'pm_saved_payment_method_id',
  confirm: true,
  show_saved_payment_methods: true,           // top-level parameter
  feature_flags: { redirect_immediately: true },
});

See all 11 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    payment_method_id="pm_saved_payment_method_id",
    confirm=True,
    show_saved_payment_methods=True,           # top-level parameter
    feature_flags={"redirect_immediately": True},
)

See all 11 lines

إن status في استجابة الرابط العميق ليس سوى إشارة إلى واجهة المستخدم. أكّد منح الوصول من خلال الاستماع إلى webhook‏ payment.succeeded على خادمك الخلفي.

Subscription with Free Trial - trial before first charge

استخدم هذه الوصفة لمنتجات الاشتراك التي توفر فترة تجريبية مجانية قبل دورة الفوترة الأولى.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://subscription/activated',
  cancel_url: 'myapp://subscription/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  subscription_data: { trial_period_days: 14 },
});

See all 14 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://subscription/activated",
    cancel_url="myapp://subscription/cancelled",
    minimal_address=True,
    customization={"show_order_details": False, "theme": "system"},
    subscription_data={"trial_period_days": 14},
)

See all 11 lines

امنح الوصول إلى الميزة عندما يتلقى خادمك الخلفي webhook‏ subscription.active، وليس عند إرجاع SDK المحمول للنتيجة. راجع دليل تكامل الاشتراكات للاطلاع على تدفق webhook الكامل.

On-Demand Mandate - save a card for future variable charges

استخدم هذه الوصفة لترميز بطاقة العميل لاستخدامها في عمليات خصم لاحقة (شحن المحافظ والدفع حسب الاستخدام وBNPL) من دون عرض تسمية “اشتراك”. يفوّض العميل طريقة الدفع مرة واحدة، ثم تخصم مبالغ متغيرة عند الطلب لاحقًا.

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

• Node.js SDK
• Python SDK

// Step 1: Authorize the mandate (no charge yet)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://mandate/authorized',
  cancel_url: 'myapp://mandate/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    show_on_demand_tag: false, // hides the "on-demand" / "subscription" label
    theme: 'system',
  },
  subscription_data: {
    on_demand: { mandate_only: true },
  },
});

// Step 2: Later, charge any amount using the subscription ID
// (received via the subscription.active webhook after mandate authorization)
// await client.subscriptions.charge(subscriptionId, {
//   product_price: 2000,         // $20.00 in cents
//   product_currency: 'USD',
//   product_description: 'Session credits',
// });

See all 26 lines

# Step 1: Authorize the mandate (no charge yet)
session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://mandate/authorized",
    cancel_url="myapp://mandate/cancelled",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "show_on_demand_tag": False,  # hides the "on-demand" / "subscription" label
        "theme": "system",
    },
    subscription_data={"on_demand": {"mandate_only": True}},
)

# Step 2: Later, charge any amount using the subscription ID
# client.subscriptions.charge(subscription_id, {
#     "product_price": 2000,  # $20.00 in cents
#     "product_currency": "USD",
#     "product_description": "Session credits",
# })

See all 23 lines

تتطلب الرسوم عند الطلب حدًا أدنى قدره 1 USD (100 سنتًا). وسيتم رفض المبالغ الأقل من 1 USD مع "value out of range". ولتفويض بقيمة صفرية، استخدم mandate_only: true كما هو موضح أعلاه، ثم اخصم 1 USD على الأقل في الاستدعاءات اللاحقة.

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

​

تدفقات الاشتراك من الأجهزة المحمولة

​

الاشتراكات المتكررة العادية

​

الاشتراكات عند الطلب

• اضبط show_on_demand_tag: false كي لا تعرض صفحة الدفع لغة “اشتراك” أو “عند الطلب”. ففي حالات استخدام ترميز البطاقة، لا يتوقع العملاء مصطلحات الاشتراك.
• بعد تفويض التفويض، سيتلقى خادمك الخلفي subscription.active. خزّن subscription_id، إذ ستستخدمه في جميع عمليات الخصم المستقبلية.

​

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

​

الترقية وخفض الخطة

​

تقليل التخلّي عن صفحة الدفع

​

تحسين النموذج

​

الملء المسبق لبيانات العميل

• العملاء الجدد: اضبط customer.email وcustomer.name من جلسة المصادقة لديك.
• العملاء العائدون: اضبط customer.customer_id لملء جميع التفاصيل المخزنة تلقائيًا.
• العملة: مرّر دائمًا billing_currency وbilling_address.country معًا.

​

أدوات الاسترداد

​

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

• الأمان: لا تضع مفتاح API في تطبيقك أبدًا. أنشئ جلسات الدفع على خادمك الخلفي ومرّر إلى العميل checkout_url الناتج فقط.
• المرجعية: تعامل مع CheckoutResult.status على أنه إشارة إلى واجهة المستخدم. امنح الوصول فقط بعد تأكيد خادمك الخلفي للدفع.
• تجربة المستخدم: اعرض حالة تحميل أثناء إنشاء خادمك الخلفي للجلسة، وتعامل مع cancelled كنتيجة عادية وليس كخطأ.
• الاختبار: استخدم وضع الاختبار وبطاقات الاختبار، وتحقق من دورة عنوان URL للإرجاع على جهاز حقيقي وكذلك على محاكي.
• التحويل: اضبط show_order_details: false وminimal_address: true لتحقيق أفضل معدلات إكمال الدفع على الأجهزة المحمولة. فنقل طرق الدفع إلى الجزء الظاهر وتقليل حقول النموذج هما التغييران الأعلى تأثيرًا.
• العملة: مرّر دائمًا billing_currency وbilling_address.country صراحةً؛ فإذا غاب أحدهما، فقد تغيّر Adaptive Currency عملة الفوترة استنادًا إلى عنوان IP الخاص بالعميل.
• الفوترة عند الطلب: اضبط show_on_demand_tag: false عند استخدام الاشتراكات عند الطلب لترميز البطاقة. لا يتوقع العملاء الذين يستخدمون تدفق شحن المحفظة رؤية لغة “اشتراك”.
• الاسترداد: فعّل استرداد سلة التسوق المتروكة في لوحة تحكم Dodo Payments لإعادة إشراك العملاء الذين لا يكملون الدفع تلقائيًا.

​

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

​

المشكلات الشائعة

• لا يصل الاستدعاء: يجب أن يطابق المخطط في returnUrl المخطط الذي سجلته. في Android يكون ذلك العنصر النائب في manifest‏ dodoCallbackScheme؛ وفي iOS وReact Native يكون نوع عنوان URL‏ Info.plist.
• تعود صفحة الدفع إلى المتصفح بدلًا من تطبيقك (iOS): لم تمرّر عنوان URL الوارد. استدعِ DodoCheckout.handleOpenURL(url) من .onOpenURL أو scene(_:openURLContexts:) أو مستمع Linking في React Native.
• PLATFORM_ERROR في Android: غالبًا ما يكون السبب عدم تطابق المخطط. وقد يظهر أيضًا إذا ضبط MainActivity قيمة android:taskAffinity="" (القيمة الافتراضية القياسية flutter create)، ما يسمح لبعض إصدارات OEM بفقدان جلسة الدفع الجارية.
• ALREADY_IN_PROGRESS: لا تزال هناك عملية دفع مفتوحة. انتظر العملية السابقة أو أغلقها قبل بدء أخرى.
• يفشل البناء بسبب عنصر نائب لم يتم حله: أضفت Android SDK لكنك لم تضبط manifestPlaceholders["dodoCallbackScheme"].
• نجح الدفع لكن لم يُمنح الوصول: هذا متوقع إذا كنت تعتمد على نتيجة الجهاز المحمول. امنح الوصول من webhook‏ payment.succeeded / subscription.active بدلًا من ذلك.
• لا يظهر Apple Pay / Google Pay على الأجهزة المحمولة: يتم تحميل صفحة الدفع داخل WebView مضمّن (WKWebView / Android‏ WebView)، ما يعطّل المحافظ وقد يتسبب في تعطل 3-D Secure. افتحها باستخدام حزمة SDK أو في متصفح النظام (Custom Tabs / SFSafariViewController).

​

موارد إضافية

• دليل تكامل الدفع
• توثيق Webhook
• عملية الاختبار
• الأسئلة الشائعة التقنية
• تخصيص جلسة الدفع
• الاشتراكات عند الطلب
• ترقية/خفض الاشتراك
• استرداد سلة التسوق المتروكة
• Customer Portal