Android

تغطي هذه الصفحة Android checkout SDK، com.dodopayments.api:checkout-android، الذي يفتح صفحة الدفع المستضافة من Dodo Payments داخل تطبيقك. لاستدعاء Dodo Payments API من خادمك، استخدم backend Kotlin SDK بدلاً من ذلك.

Checkout Sessions API

أنشئ checkout_url الذي يفتحه SDK هذا.

Mobile Integration Guide

أفضل الممارسات لتدفقات الدفع عبر الأجهزة المحمولة.

يفتح Android SDK صفحة الدفع المستضافة من Dodo Payments في Custom Tab (androidx.browser.customtabs)، ويعيد CheckoutResult مكتوب النوع عند إكمال العميل للدفع أو مغادرته. ينشئ خادمك جلسة الدفع ويرسل checkout_url الخاص بها إلى التطبيق. لا يحتوي SDK على أي كود للشبكة ولا يحتفظ بأي API key، ولذلك لا يستدعي Dodo Payments API مطلقاً. المتطلبات: minSdk 23 وKotlin وJava 17. يعتمد SDK فقط على androidx.activity وandroidx.browser وkotlinx-coroutines-android.

التثبيت

Add the Dependency

أضف SDK من Maven Central إلى build.gradle.kts الخاص بوحدة تطبيقك:

build.gradle.kts

dependencies {
    implementation("com.dodopayments.api:checkout-android:1.1.0")
}

يتطلب تخصيص المظهر الإصدار 1.1.0 أو إصداراً أحدث.

عيّن مخطط callback باعتباره manifest placeholder في Gradle. يعلن manifest الخاص بـ SDK نفسه عن intent filter لنشاط إعادة التوجيه باستخدام placeholder ${dodoCallbackScheme}، ولذلك فإن هذه الخاصية هي خطوة الإعداد الوحيدة. لا تضف أي manifest XML:

build.gradle.kts

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

استخدم المخطط نفسه في CheckoutParams.returnUrl، مثل myapp://checkout/return، وعيّن عنوان URL نفسه باعتباره return_url الخاص بجلسة الدفع عند إنشاء خادمك للجلسة. يطابق SDK عنوان URL للعودة وفقاً للمخطط والمضيف والمسار، ويتجاهل query string. لا يلزم أن يحمّل عنوان URL صفحة حقيقية.

إذا حذفت placeholder، يفشل البناء بسبب خطأ unresolved-placeholder. وإذا لم يطابق placeholder مخطط returnUrl، فإن SDK يرمي PLATFORM_ERROR قبل فتح صفحة الدفع.

الاستخدام

يوفر SDK طريقتين لبدء الدفع: activity result launcher ودالة suspend. ويعيد كلاهما CheckoutResult نفسه.

Launcher (Recommended)
Suspend Function

سجّل العقد باستخدام registerForActivityResult، ثم شغّله:

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> reconcileAbandonedSession() // outcome unknown, not a failure
            CheckoutStatus.PENDING -> reconcileAbandonedSession()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl, // from your backend's checkout session
        returnUrl = "myapp://checkout/return"
    )
)

استخدم هذا الأسلوب متى أمكن. يسلّم Android النتيجة من خلال ActivityResultRegistry الخاص به، ولذلك تبقى النتيجة بعد موت العملية.

استدعِ DodoCheckout.start من coroutine scope:

import androidx.lifecycle.lifecycleScope
import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout
import kotlinx.coroutines.launch

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
lifecycleScope.launch {
    val result = DodoCheckout.start(
        activity = this@MyActivity,
        params = CheckoutParams(
            checkoutUrl = checkoutUrl, // from your backend's checkout session
            returnUrl = "myapp://checkout/return"
        ),
        onEvent = { event -> println(event.name) } // logging only
    )

    when (result.status) {
        CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
        CheckoutStatus.FAILED -> showFailure()
        CheckoutStatus.CANCELLED -> reconcileAbandonedSession() // outcome unknown, not a failure
        CheckoutStatus.PENDING -> reconcileAbandonedSession()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

يتلقى onEvent أحداث checkout.opened وcheckout.return_received وcheckout.closed. استخدمها للتسجيل فقط، ولا تستخدمها مطلقاً لتحديد النتيجة.

ينتظر هذا الأسلوب CompletableDeferred داخل الذاكرة، ولذلك لا تبقى النتيجة بعد موت العملية. يتوفر onEvent في هذا الأسلوب فقط، وليس مع launcher.

ما الذي تعنيه النتيجة

ينشئ SDK CheckoutResult من query parameters الموجودة في عنوان URL للعودة.

حقل status هو تلميح لواجهة المستخدم، وليس دليلاً على الدفع. قبل منح الوصول، أكّد الدفع على خادمك باستخدام webhook أو نقطة النهاية Get Payment Detail.

CheckoutStatus

مطلوب

إحدى خمس قيم:

SUCCEEDED: يحتوي عنوان URL للعودة على status=succeeded (دفعة لمرة واحدة) أو status=active (اشتراك).
FAILED: تم رفض الدفع (status=failed).
CANCELLED: أغلق العميل Custom Tab قبل وصول عنوان URL للعودة. لا يعرف SDK النتيجة، وقد يكون الدفع قد نجح، لذا لا تعرض شاشة فشل. عالج الجلسة المتروكة بدلاً من ذلك.
PENDING: تتم تسوية الدفع لاحقاً (status=processing أو أي قيمة requires_*)، أو كانت المعلمة status مفقودة أو غير معروفة. عالجها مثل CANCELLED.
EXPIRED: انتهت صلاحية جلسة الدفع (status=expired).

String?

معلمة query payment_id، عند تضمينها في عنوان URL للعودة. اعرضها في واجهة المستخدم، لكن لا تستخدمها لمنح الوصول. راجع التحقق من الدفع.

String?

معلمة query subscription_id. يتم تعيينها لعمليات دفع الاشتراكات.

List<String>?

معلمة query license_key. يتم تعيينها عندما تتضمن عملية الدفع منتجات مفاتيح ترخيص.

String?

معلمة query email. يتم تعيينها عندما تجمع عملية الدفع عنوان بريد إلكتروني.

Map<String, String>

كل query parameter من عنوان URL للعودة، حرفياً.

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

Webhooks

استمع إلى أحداث الدفع في الوقت الفعلي.

Get Payment Detail

استعلم عن حالة الدفع عند الطلب.

لا تمنح الوصول إلا بعد أن يؤكد أحد هذه الخيارات الدفع، على سبيل المثال باستخدام webhook payment.succeeded أو subscription.active. لا تعتمد على CheckoutResult.status وحده.

تخصيص المظهر

لتغيير شريط أدوات Custom Tab وأزراره ونظام الألوان، مرّر BrowserCustomization باعتباره customization إلى CheckoutParams. كل حقل اختياري وقيمته الافتراضية null. بالنسبة إلى حقل null، لا يعيّن SDK هذا الخيار، ولذلك يطبّق المتصفح الذي يستضيف Custom Tab قيمته الافتراضية الخاصة.

لون خلفية شريط الأدوات، باعتباره قيمة ARGB من نوع Color.

لون شريط التنقل، باعتباره قيمة ARGB من نوع Color.

لون الفاصل أعلى شريط التنقل، باعتباره قيمة ARGB من نوع Color.

CloseButtonStyle?

يعرض DEFAULT رمز النظام “X”. ويعرض BACK سهماً للعودة يرسمه SDK.

CloseButtonPosition?

جانب شريط الأدوات الذي يظهر فيه زر الإغلاق: START أو END.

يعرض رمز المشاركة في شريط الأدوات. يخفيه false.

Boolean?

يعرض عنوان الصفحة أسفل عنوان URL في شريط الأدوات.

Boolean?

يخفي شريط الأدوات تلقائياً أثناء تمرير الصفحة.

Boolean?

يعرض “إضافة الصفحة إلى الإشارات المرجعية” في قائمة الخيارات الإضافية.

Boolean?

يعرض “تنزيل الصفحة” في قائمة الخيارات الإضافية.

ColorScheme?

يفرض LIGHT أو DARK هذا المظهر بصرف النظر عن إعداد النظام على الجهاز. ويتبع SYSTEM إعداد النظام.

يعيد هذا المثال استخدام checkoutLauncher من الاستخدام:

import android.graphics.Color
import com.dodopayments.checkout.BrowserCustomization
import com.dodopayments.checkout.CheckoutParams

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            colorScheme = BrowserCustomization.ColorScheme.DARK,
        )
    )
)

الأخطاء

يرمي DodoCheckout.start الخطأ CheckoutError فقط عند إساءة الاستخدام أو حدوث فشل في النظام الأساسي. اقرأ السبب من CheckoutError.code:

INVALID_CHECKOUT_URL: إن checkoutUrl ليس عنوان URL لجلسة دفع https (مساره يبدأ بـ /session/) على checkout.dodopayments.com أو test.checkout.dodopayments.com.
INVALID_RETURN_URL: إن returnUrl ليس عنوان URL مطلقاً يتضمن مخططاً ومضيفاً.
ALREADY_IN_PROGRESS: توجد عملية دفع أخرى قيد التشغيل. يمكن تشغيل عملية دفع واحدة فقط في كل مرة.
PLATFORM_ERROR: فشل غير متوقع في النظام الأساسي، بما في ذلك مخطط returnUrl لا يطابق placeholder dodoCallbackScheme الخاص بك.

تكون عملية إلغاء العميل، أو الدفع المرفوض، دائماً نتيجة (CANCELLED أو FAILED)، وليست خطأً مرمياً. مع launcher، تُرمى أخطاء التحقق من launcher.launch(...). لا يمكن تمرير فشل النظام الأساسي بعد الإطلاق من خلال activity result callback، ولذلك يعيد launcher CANCELLED مع رمز الخطأ في raw["error"].

الجلسات المتروكة

يسجل SDK جلسة الدفع عند بدء الدفع، ويمسح السجل فقط عندما ينتهي الدفع بالحالة SUCCEEDED أو FAILED أو EXPIRED. يبقى السجل عند إيقاف التطبيق أثناء الدفع، وبعد نتيجة CANCELLED أو PENDING، لأن SDK لا يعرف النتيجة في هذه الحالات. تحقّق من وجوده عند تشغيل التطبيق في المرة التالية وبعد كل نتيجة CANCELLED أو PENDING:

// context is any Context, such as your Activity.
DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // Ask your backend for the outcome of abandoned.sessionId, and show it.
    // Clear the record only after the outcome is final:
    DodoCheckout.clearAbandonedSession(context)
}

يمثل abandoned.sessionId معرّف جلسة الدفع، الذي يبدأ بـ cks_. ويمثل abandoned.createdAt وقت بدء الدفع، بوصفه epoch timestamp بالمللي ثانية. يستطيع خادمك البحث عن الجلسة باستخدام Get Checkout Session، الذي يعيد payment_id وpayment_status الخاصين بها. إلى أن يصل الدفع إلى حالة نهائية، اعتبره قيد الانتظار، وليس فاشلاً.

Mobile Integration Guide

أفضل الممارسات لتدفقات الدفع عبر الأجهزة المحمولة.

Kotlin SDK

Backend SDK للعمليات من جهة الخادم.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

التثبيت

الاستخدام

ما الذي تعنيه النتيجة

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

Webhooks

Get Payment Detail

تخصيص المظهر

الأخطاء

الجلسات المتروكة

ذات صلة

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​التثبيت

​الاستخدام

​ما الذي تعنيه النتيجة

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

Webhooks

Get Payment Detail

​تخصيص المظهر

​الأخطاء

​الجلسات المتروكة

​ذات صلة

Mobile Integration Guide

Kotlin SDK

التثبيت

الاستخدام

ما الذي تعنيه النتيجة

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

تخصيص المظهر

الأخطاء

الجلسات المتروكة

ذات صلة