Android

هذا هو Android checkout SDK الرسمي (com.dodopayments.api:checkout-android)، المخصص لفتح صفحة الدفع المستضافة من Dodo. وهو يختلف عن backend Kotlin SDK، الذي يستدعي Payments API من Dodo من خادمك.

Checkout Sessions API

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

Mobile Integration Guide

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

يفتح Android SDK صفحة الدفع المستضافة من Dodo في Chrome Custom Tab باستخدام androidx.browser.customtabs. ولا يتضمن أي شيفرة للشبكات ولا يحتفظ بأي API key. تمرر checkoutUrl من جلسة الدفع على خادمك، ويعيد SDK قيمة CheckoutResult مكتوبة النوع عند إكمال المستخدم للتدفق أو مغادرته. المتطلبات: minSdk 23، Kotlin، Java 17.

التثبيت

Add the Dependency

build.gradle.kts

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

عيّن مخطط callback كعنصر نائب في بيان Gradle. يعلن البيان الخاص بالمكتبة مسبقًا عن عامل intent filter لنشاط إعادة التوجيه باستخدام الرمز ${dodoCallbackScheme}، لذا فإن هذه الخاصية الواحدة تمثل كامل إعداد التكامل — ولا تحتاج إلى إضافة أي XML للبيان:

build.gradle.kts

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

يجب أن تتطابق القيمة مع المخطط في CheckoutParams.returnUrl (مثلًا myapp://checkout/return).

إذا حذفت العنصر النائب بالكامل، يفشل البناء فورًا بسبب خطأ عنصر نائب غير محلول، بدلًا من الفشل بصمت وقت الدفع. وإذا عيّنته لكنه لا يتطابق مع مخطط returnUrl، فإن DodoCheckout.start يرمي PLATFORM_ERROR قبل عرض أي شيء.

الاستخدام

يدعم SDK أسلوبي استدعاء.

Launcher (Recommended)
Suspend Function

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

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

private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> dismiss()
            CheckoutStatus.PENDING -> showPending()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

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

فضّل هذا الأسلوب. تُسلَّم النتيجة من خلال ActivityResultRegistry المُدار بواسطة نظام تشغيل Android، لذا فهي تظل متاحة بعد توقف العملية.

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

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

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 -> dismiss()
        CheckoutStatus.PENDING -> showPending()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

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

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

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

CheckoutStatus

مطلوب

واحد من SUCCEEDED أو FAILED أو CANCELLED أو PENDING أو EXPIRED.

String?

يُعيَّن عند تضمين عنوان URL للإرجاع. اعرضه في واجهة المستخدم، ولا تستخدمه لمنح صلاحية الوصول. راجع قسم التحقّق من الدفع أدناه.

String?

يُعيَّن لعمليات الدفع الخاصة بالاشتراكات.

List<String>?

يُعيَّن عندما تتضمن عملية الدفع منتجات بمفاتيح ترخيص.

String?

يُعيَّن عندما تجمع عملية الدفع بريدًا إلكترونيًا.

Map<String, String>

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

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

Webhooks

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

Get Payment Detail

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

لا تمنح المستخدم صلاحية الوصول إلا بعد أن يؤكد أحد هذين الخيارين الدفع. لا تعتمد على CheckoutResult.status وحده.

الأخطاء

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

INVALID_CHECKOUT_URL: ليس عنوان URL لجلسة checkout.dodopayments.com صالحًا.
INVALID_RETURN_URL: ليس عنوان URL مطلقًا صالحًا.
ALREADY_IN_PROGRESS: عملية دفع قيد التشغيل بالفعل.
PLATFORM_ERROR: عطل غير متوقع في المنصة، بما في ذلك returnUrl الذي لا يتطابق مخططه مع العنصر النائب dodoCallbackScheme.

يكون إلغاء المستخدم أو رفض الدفع دائمًا نتيجة (CANCELLED أو FAILED)، وليس خطأً مُلقى. باستخدام أسلوب المشغّل، تُلقى أخطاء التحقّق من launcher.launch(...).

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

إذا أُغلِق التطبيق أو أوقفه المستخدم قسرًا أثناء الدفع، يحفظ SDK الجلسة محليًا. عند تشغيل التطبيق في المرة التالية، تحقّق من وجود جلسة متروكة وسوِّ حالتها مع خادمك الخلفي:

DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession(context)
}

إن abandoned.createdAt هو طابع زمني للعصر بوحدة المللي ثانية.

ذو صلة

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

التثبيت

الاستخدام

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

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

الأخطاء

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

ذو صلة